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Preface 


The more I learned about REXX for my Writing OS/2 REXX Programs book, the 
more impressed I became with the language. REXX is both extremely easy to use 
and very powerful. It’s hard to imagine any programming task you might want to un¬ 
dertake that REXX cannot handle. 

However, REXX has a command-line interface that seems out-of-date for the 
graphical user interface (GUI) of OS/2. Additionally, this command-line interface re¬ 
quires a great deal of coding to put all but the simplest information on the screen. As 
powerful as REXX is, its interface needs a lot of work. 

This is where visual front-ends like VX-REXX come in. VX-REXX provides a 
graphical transplant for REXX. It handles the user interface for REXX using a GUI, 
with very little coding on the programmer’s part. You can create very complex 
screens by drawing objects and assigning properties to them. Often, only a few lines 
of REXX code are needed to manipulate the interface, and even then VX-REXX will 
help you write them. 

For example, I wrote a program called INTERACT.CMD for Writing OS/2 REXX 
Programs that simulated a single line of full-screen editing under REXX. This pro¬ 
gram took 100 lines of code and dozens of hours to debug. Doing the same thing with 
VX-REXX took five minutes and a couple of lines of code! If your REXX programs 
need to do more than display text on the screen in teletype fashion, then you need 
VX-REXX. 

I wrote the previous paragraphs at the beginning of this project and certainly 
every word in them is true. However, now that I’ve reached the end of the project I 
must say that I’m far more impressed with VX-REXX than I ever thought possible. 
Not only does it make adding very fancy graphical front ends to REXX easy, but it re¬ 
duces the amount of coding most programs need by a large percentage and makes 
writing that code easier. Every single REXX programmer needs to own VX-REXX. 
After reviewing this book, I’m sure you’ll agree with me. 


xiv 



Introduction 


REXX is a very powerful programming language. Unfortunately, with the exception 
of the rudimentary PM-REXX, it suffers from a primitive teletype-like user inter¬ 
face—which certainly isn’t the user interface you’d expect in a fantastic graphical 
environment like OS/2. VX-REXX changes all that by providing the REXX program¬ 
ming language with a great visual interface. 

If a visual user interface to REXX was all it gave you, VX-REXX would be a great im¬ 
provement and a real bargain. However, VX-REXX does much, much more. It com¬ 
pletely takes over the burden of programming every aspect of the user interface. Want 
users to enter their names? Just draw a text-entry box on the screen and add one line 
of code to read the contents of the box. Want to have users confirm something? Just 
draw a button on the screen (or two, three, or as many buttons as you need) and VX- 
REXX will handle all the button management; all you need to do is add the REXX code 
telling the program what to do once a user clicks on the button. Basically, VX-REXX 
takes over the dull, boring parts of programming, leaving you free to concentrate on 
the fun parts—plus, it gives you a fantastic user interface in the process. 

The manual for VX-REXX is an excellent reference for the program. However, its 
tutorial section is fairly short and new users trying to learn the language might need 
more help than the manual offers. Which is where this book comes in. 

This book doesn’t try to duplicate the material in the Watcom VX-REXX manual, 
although there is naturally some overlap. You already have that available to you both 
in printed and online versions. Rather, this book concentrates on teaching you the 
fundamentals of using VX-REXX while leaving most of the reference material to the 
VX-REXX manual. 

This book also doesn’t try to teach you REXX programming. To be honest, that is 
a topic that requires a full book in itself. Using VX-REXX requires that you know how 
to program in REXX since VX-REXX provides a graphical user interface to your 
REXX programs rather than replacing your REXX programs. If you feel that you 
need help learning REXX, try my Writing OS/2 REXX Programs, also available from 
McGraw- Hill . Two other excellent REXX references are The REXX Language by 
Mike Cowlishaw (ISBN 0-13-780651-5) and Programming in REXX by Charles 
Daney (ISBN 0-07-015305-1). For quick reference, I also keep a copy of the REXX 
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Reference Summary Handbook from CFS Nevada right beside my computer. You 
can order this book directly from them by calling 702-732-9616. 

The Included CD-ROM 

This book includes a CD-ROM, which contains the following material: 

VX-REXX demo version. If you already have VX-REXX, use that version. If you’ve 
purchased this book before deciding to purchase VX-REXX, however, there’s a demo 
version of the program on the CD-ROM, and you can use it to run all the example 
programs. In fact, there are only two differences between the demo version and ver¬ 
sion 2.0b of VX-REXX; the demo version doesn’t allow you to save your work nor cre¬ 
ate .EXE files. But you can load any of the sample programs and run them from the 
Run menu. You can modify and experiment with these programs, and you can even 
write new programs and run them with the demo version. You just can’t save the 
modified or new programs. I’m sure that once you’ve seen the demo version in ac¬ 
tion, you’ll want to purchase the full version from Watcom. 

Before using the demo version, you must install it from the CD-ROM onto your 
hard disk. To do this, go to the command line, change to the root directory of your 
CD-ROM drive, and type setup. The setup program will first prompt you for the sub¬ 
directory in which to store the program. Of course, it must be a subdirectory on your 
hard disk and not the CD-ROM. I suggest C:\VXREXX, but you’re free to use any 
name you want. The files are too large to install on a floppy disk. 

VX-REXX is normally installed from two floppy disks, so the installation program 
will next prompt you for the location of diskl and disk2. These are the \DEMO\DISKl 
and \DEMO\DISK2 subdirectories on the CD-ROM, respectively. Enter these loca¬ 
tions when prompted and be sure to include the drive letter for your CD-ROM drive. 

VXREZ. The VXREZ program discussed in the book is also included on the CD- 
ROM, in the YVXREZ subdirectory. Instructions for installing and using VXREZ can 
be found in this subdirectory. 

Sample programs. These are all the programs discussed in the book. They branch 
off the \EXAMPLES subdirectory, with each program stored in its own subdirectory. 
For example, the Viewlcon program is stored in the \EXAMPLES\VIEWICON subdi¬ 
rectory. For each program, the disk contains the complete source code, compiled 
.EXE version of the program, and any supporting files. 

If you’re going to modify any of these programs, first copy them to your hard disk 
or a floppy disk. Additionally, many of these programs expect to find supporting files 
in the same subdirectory as the program files, so make sure that the working subdi¬ 
rectory setting under Run on the Options menu points to that subdirectory. 

If you want to run the compiled .EXE files on the CD-ROM, the file VROBJ.DLL 
must be installed in either the current subdirectory or a subdirectory on your path. 
You can find it in the \DLL file on the CD-ROM. If you install the demo version of VX- 
REXX, it will automatically include VROBJ.DLL for you. 

If you don’t have access to a CD-ROM drive, for a nominal charge I’ll send you a 
1.44MB 3.5-inch floppy disk containing just the sample programs . Due to space 
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limitation, the floppy disk won’t include the icons, demo version of VX-REXX, 
VXREZ, or IconEase. Send $6.00 by check or money order to: 

Ronny Richardson 
P.O. Box 622 
Quincy, IL 162306-0622 

Be sure to include your mailing address. The offer expires 12/31/95. 

Icons. Once you’ve written programs you plan on using, you’ll want to install 
them on the desktop, and for that you’ll need an icon for each program. The CD- 
ROM contains over 1,800 icons, grouped by name. All the icons with names start¬ 
ing with an A, for example, are stored in the \ICONS\A subdirectory. You can view 
them with the Viewlcn3 or V12-VGA programs, included on the CD-ROM with the 
example programs. 

IconEase. IconEase is a shareware program that makes viewing and using icons 
easy. The program automatically arranges the icons alphabetically in a tabbed note¬ 
book. Click on a tab for the first letter of the icon name, and then click on the indi¬ 
vidual icon names to view them. Once you find one you want to use, clicking on a 
single button will place it in the clipboard for easy use. I’ve compiled all 1,800 of the 
icons on the CD-ROM into a single IconEase database, so you can access them all 
through IconEase. 

Please keep in mind that this is a shareware program, which I’ve included for your 
convenience. Shareware is a try-it-before-you-buy-it proposition. If you try 
IconEase, like it, and continue to use it, you’re expected to register it with its author, 
Dave Lester. Full instructions on how to do this are included in the IconEase subdi¬ 
rectory. Registration of IconEase is not included in the price of this book. 

Hardware and Software 

Writing a computer book is difficult. I never know what type of hardware and soft¬ 
ware you have; I don’t even know what version of the operating system you’re using. 
In writing about VX-REXX, however, I’m more fortunate than many writers. Most 
VX-REXX programs will run on any hardware configuration that supports OS/2 2.0. 
While I wrote this book using OS/2 2.1, most of the programs should run under OS/2 
2.0. For the examples in this book, I assume that the files supporting external com¬ 
mands like FORMAT and BACKUP are either in the current subdirectory or in the 
path when an example program requires one of them. 

I wrote this book using version 2.0 of VX-REXX. Most of the examples won’t run in 
earlier versions of VX-REXX. If you’re still using version 1.0, you should contact 
Watcom regarding an upgrade, as version 2.0 adds a bunch of new features. 

Writing This Book 

I wrote this book using a Gateway 2000 486/66 and printed everything on an HP 
Laserjet III with a Pacific Data PacificPage PostScript cartridge. The word processor 
I used for everything except the programs and tables was DeScribe 4.0.1 edited the 
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programs using the editor that’s built into VX-REXX. I created all the tables using 
QuarkXPress for the Macintosh running the Tableworks Plus extension. The screen 
shots were captured using the OS/2 Presentation Manager screen-capture program 
PMCamera by Jurg Von Kanel. 

I wrote all the VX-REXX programs in this book and took all the screen shots using 
an SVGA display. During the technical review phase, the experts at Watcom pointed 
out that some of the programs wouldn’t run on a standard VGA display. I’ve gone back 
to the programs and corrected this. For this reason, programs might appear slightly 
different when you run them than they do in the screen shots. They’ll still function 
the same. I was unable to convert a few of the programs. These are noted in the text. 
Where possible, I’ve included a separate version of these programs designed espe¬ 
cially for a VGA display. 

If you’re planning on writing programs for other users, take note of my mistake 
and make sure your programs will run at the lower VGA resolution—which has fewer 
pixels, so programs appear larger—before releasing those programs. If you design 
your programs in VGA mode, they’ll always run at higher resolutions. 


Conventions 

You should keep a few important pieces of information in mind when reading this book: 

■ The numbered function keys on the keyboard are shown as FI through F12. Many 
older keyboards have ten function keys on the left side of the keyboard, labeled 
from FI to F10. Newer keyboards have twelve function keys, FI to F12, generally 
along the top of the keyboard. 

H Enter stands for the Enter or Return key, which can also be represented on the 
keyboard as Rtrn or a bent arrow. Most other named keys, like Del or Tab, are also 
referred to by their name. The directional keys are simply up, down, right, and left 
arrow. 

■ Pieces of programs broken out from the regular text are shown in an alternate 
typeface. The names of keys you hit, like F6 or Enter, are in regular type. 

88 A key combination is when you hold down one key, hit another key, and then re¬ 
lease both keys, for example Ctrl and then Z. This is shown as Ctrl-Z. 

s Any command inside brackets, [ ], is optional. Brackets are generally used in the 
syntax of a command. In the following, for example: 

DIR [/P] 

the /P switch is optional. It causes the listing to pause each time the screen is full. 
Pressing any key restarts the listing. 

0 Variable information in command lines, lik e filename and path, is shown in italic. 
It represents information that changes. 
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■ Most of the commands in this book are in uppercase when shown on a command 
line. For the most part, OS/2 doesn’t care. Entering DIR, dir, or DiR on the com¬ 
mand line are all the same to OS/2. 

This is a programming book, so a lot of programs are used as illustrations. Since the 
purpose of this book is to teach you to use VX-REXX to add a graphical user interface 
to your REXX programs, most of the time I’ll show only the portion of code devoted 
to the interface between REXX and VX-REXX. Most of this code is fairly short, so I’ll 
list it as part of the text of the book rather than as stand-alone figures. When a longer 
example is required to illustrate a point and the full program is important to the illus¬ 
tration, that program will be presented in a table, with the source code printed on the 
left side and a line-by-line explanation printed on the right side. The complete source 
code for each example program discussed in this book is included on the CD-ROM 
that comes with this book, as are the compiled .EXE files and all supporting files. 


Corrections and Improvements 

Should you discover any problems or bugs in the sample programs that come with 
this book, please let me know and I’ll post corrections in the VX-REXX area of the 
Watcom forum on CompuServe. Enter GO POWERS to reach this forum. 


REXX Language Association 

If you’re truly interested in programming in the REXX language, you’ll want to join 
REXXLA, the REXX Language Association. For your $25-a-year membership dues, 
you’ll get a quarterly newsletter with great REXX tips, electronic resources for ac¬ 
cess to language experts, participation in standards development, and much more. 
For more information, contact: 

REXXLA Membership 

6300 North River Rd., Suite 501 

Rosemont, IL 60018 


Ideas 


If this book causes you to develop a nice VX-REXX program or raises a VX-REXX-re- 
lated question not currently answered in the book, write to me and let me know. Your 
hint or question just might show up in the next edition of this book! The address is: 

Ronny Richardson 
P.O. Box 622 
Quincy, IL 62306-0622 

If you’re active in the online community, you can also reach me on CompuServe, 
where my address is 70322,3100. 
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Chapter Summaries 

Section I: Introductory VX-REXX Topics 

There is a core of knowledge that anyone using VX-REXX needs to know. The first 
12 chapters in this section cover that knowledge. Chapter 13 describes the sample 
programs that come with VX-REXX. I strongly encourage you to read each one of 
these chapters in sequence. 

Chapter 1: Getting Started. This chapter describes the mechanics of using VX- 
REXX by creating a simple example program. 

Chapter 2: Descriptive Text Objects. Chapter 1 shows how to use a Descriptive Text 
object in a program. Chapter 2 continues this discussion by showing how to use De¬ 
scriptive Text objects in more complex programs. 

Chapter 3: Dressing Up Your Windows. Now that you’ve seen how to design simple 
programs in VX-REXX, you’ll see how to dress up the “window” that surrounds that 
program. 

Chapter 4: PushButton Objects. Buttons that the user pushes to initiate some ac¬ 
tion are a common element of VX-REXX programs. In fact, several of the example 
programs in earlier chapters have these buttons. This chapter expands on the use of 
PushButton objects in your programs. 

Chapter 5: Other Buttons. RadioButton and CheckBox objects offer an easy way to 
ask users simple questions, where they select from a list of options. RadioButton ob¬ 
jects let users select only one option, while CheckBox objects allow them to select all 
that apply. This chapter shows you how to use these buttons in your programs. 

Chapter 6: Getting Text Data from the User. When you need to get information from 
users, such as their name, you need an object designed to allow them to type in in¬ 
formation. EntryField objects are used to get a single line of information from users. 
MultiLine EntryField objects are used for multiple lines of information. This chapter 
shows you how to use these in your programs. 

Chapter 7: Getting Specific Information from the User. When you need to get a file¬ 
name from users or you want them to pick between a limited number of options us¬ 
ing buttons, VX-REXX offers specialized functions to perform these tasks. The 
VRFileDialog function is used to get a filename from users with a dialog box that pre¬ 
sents a graphical representation of your hard disk—its subdirectories and files. The 
VRMessage function presents users with a limited number of options to a situation. 
This chapter shows you how to use these and a few other specialized VX-REXX func¬ 
tions in your programs. 

Chapter 8: Selecting Values from a List. When you need users to select items from a 
predefined list, VX-REXX has three objects to do that. The ListBox object limits 
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users to the items you predefine in the list. The ComboBox object lets users pick 
from a list of items or enter their own values. The DropDown ComboBox object per¬ 
forms the same task as the ComboBox object, but takes up less screen real estate by 
displaying the list of items only when the user clicks on an arrow. This chapter shows 
you how to use these objects. 

Chapter 9: Dressing Up Your Programs with Pictures. OS/2 is a visual environment, 
where files and subdirectories can be represented by icons. This allows users to 
quickly become productive without having to do a lot of onscreen reading. VX-REXX 
also allows you to use icons and pictures in your programs to a limited degree. This 
chapter discusses those features. 

Chapter 10: More on Getting information from the User. VX-REXX has several more 
objects to get information from users. This chapter discusses them. 

Chapter 11: Other Objects. VX-REXX has a few additional objects that haven’t yet 
been covered. This chapter discusses them. 

Chapter 12: VX-REXX Functions. VX-REXX has a number of functions that replace 
REXX and RexxUtil functions, as well as OS/2 commands. It also has functions to 
configure itself at runtime. This chapter describes these functions. 

Chapter 13: VX-REXX Sample Programs. VX-REXX comes with a number of sample 
programs. This chapter provides a detailed look at them. 

Section II: Advanced VX-REXX Topics 

The chapters in this second section cover the more advanced VX-REXX topics. It 
isn’t necessary to understand each of these topics in order to write good programs, 
but I encourage you to read those chapters that interest you or that address a pro¬ 
gramming problem you’re facing. It isn’t necessary to read these chapters in any par¬ 
ticular order, so you can limit yourself to just those you need. 

Chapter 14: Working with Multiple Windows. Many programs need more than one 
window. It’s often handy to have secondary windows pop up and ask for specific in¬ 
formation when you don’t want the main window to remain cluttered. For example, 
you might use a pop-up window to ask the user to confirm some action or to provide 
a filename. This chapter discusses working with more than one window. 

Chapter 15: Menus. Menus can consolidate a lot of buttons into a list of possible ac¬ 
tions displayed across the top of the program. As an additional advantage, menus 
make it easy to logically group options. This chapter shows how to add a menu to 
your application and how to attach a pop-up menu to any object in your program. 

Chapter 16: Using Help and Hints. Next to well-crafted written documentation, on¬ 
line help is the best aid you can provide for your users. This chapter shows you how 
to add help to your programs. 
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Chapter 17: Multithreaded Applications, OS/2 is an operating system that was de¬ 
signed from the very beginning to easily do more than one thing at a time. So far, 
each program you’ve seen has done only one thing at a time. That wastes the power 
of OS/2. This chapter shows you how to write applications that do more. 

Chapter 18: Using the External Data Queue, REXX queues allow different REXX and 
VX-REXX programs to communicate with each other, even when they run at differ¬ 
ent times in different sessions. This chapter explains how to take advantage of these 
very powerful queues. 

Chapter 19: Working with Configuration Files. A well-crafted configuration file can 
make your program look very professional. This chapter shows you how to use them. 

Chapter 20: Working with Direct Data Exchange. Direct data exchange, or DDE, is 
an OS/2 facility that allows two applications running under OS/2 to exchange data. 
VX-REXX can serve as a DDE client. This chapter shows you how to use DDE in your 
programs. 

Chapter 21: Debugging VX-REXX Programs. Finding mistakes in a program is a 
painstaking and thankless job, but it’s one you must do if you write anything but the 
simplest programs. This chapter shows you how. 

Chapter 22: VX-REXX Summaries. These tables quickly summarize the properties, 
events, and methods available in VX-REXX and tell you which objects they apply to. 

Chapter 23: Program Summaries. This chapter provides a brief summary of all the 
REXX and VX-REXX programs that come on the CD-ROM that comes with this book. 
It also summarizes the sample programs that come with VX-REXX itself. 
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VX-REXX is far more than a set of library functions you attach to REXX and call 
when you need to use one of its functions. Rather, VX-REXX is more like a graphical 
glove that wraps itself around REXX, insulating it from the command line. With VX- 
REXX, all communications between the user and your REXX program are handled in 
a graphical fashion. You can see this in Figure 1.1, which shows MESSAGE.EXE, a 
simple VX-REXX program, running. 

As you can see, the standard character input/output screen you normally see 
when running a REXX program is missing. In its place is a graphical user interface 
with a message to the user and two buttons for the user to click. In fact, because it 
runs as an OS/2 Presentation Manager application, the option of sending output to 
the standard command line isn’t available to VX-REXX programs. 



Figure 1.1 A VX-REXX program running. 


1 
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This chapter presents an overview of using VX-REXX. Since much of this infor¬ 
mation is already available in the VX-REXX manual, I’m going to quickly review only 
the most important features. 


Starting VX-REXX 

When you program in VX-REXX, you’re working on what the VX-REXX manual calls 
a project. A project is a collection of one or more window and code files that form a 
single program. I find this notation more confusing than helpful. VX-REXX considers 
a program a project while you’re working on it and & program once it’s done. I don’t 
see the need for the distinction, so I’ll call everything programs both before and af¬ 
ter they’re finished. 

There are two main ways to start VX-REXX. The first is to double-click on its icon 
in the desktop shell. This loads VX-REXX without having a program loaded, as 
shown in Figure 1.2. When starting a new program, you can also drag a template out 
of the VX-REXX folder to the folder where you want to save the program. Of course, 
you can also use the other OS/2 methods, such as double-clicking on a .VXP program 
file or running the program from an OS/2 command-line prompt. 

To make VX-REXX instantly available, I created a shadow of the editor icon and 
placed that shadow on the desktop. Now I can instantly start VX-REXX by double¬ 
clicking on that icon. I also placed shadows of all the programs I’m currently working 
on in a folder on the desktop. If I know I want to work on a particular program, I can 
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Figure 1.2 VX-REXX without a project loaded. 
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| New 

Open... 

Save 

Save as... 

Ctrl+N 

Ctrl+O 

Ctrl+S 

New window file 

Ctrl+W 

New code file 

Ctrl+C 

Make EXE file... 

Ctrl+X 

Make macro... 

Ctrl+M 


Figure 1.3 The VX-REXX Project 
menu. 


open that folder and quickly drag a program icon to the VX-REXX shadow, or just 
double-click on it to start VX-REXX with that program loaded. 


Managing Files 

Since VX-REXX works with entire programs rather than individual files, the tradi¬ 
tional Files menu is replaced with a Projects menu (since VX-REXX calls programs 
projects), shown in Figure 1.3. Use this menu to load new programs, save the pro¬ 
gram you’re working on, and compile a program into an .EXE program file. VX-REXX 
doesn’t allow you to load more than one program into memory at once, but OS/2 al¬ 
lows you to run multiple versions of VX-REXX, which accomplishes almost the same 
thing. 

There is, however, one drawback to this approach. You can switch to one version 
of VX-REXX, copy code to the clipboard, switch to another version, and paste the 
code. But this doesn’t work when pasting VX-REXX objects. To paste a VX-REXX 
object, you must stay in the same session. You can load one program, copy the object 
to the clipboard, unload that program, load a second program, and paste the object 
in the second program. As you can imagine, this is more cumbersome than loading 
two different programs in the same VX-REXX session. 


Running a Program 

To run a program outside of VX-REXX, you must use the Make EXE File option 
from the Projects menu. There are many times when you’ll need to run the pro¬ 
gram you’re currently working on in VX-REXX to make sure it’s executing prop¬ 
erly. Do this using the Run menu, as shown in Figure 1.4. If your program needs 
command-line parameters or needs to run in a special subdirectory, you can use 
the Run option on the Options menu to configure those options. This is shown in 
Figure 1.5. 




MESSAGE 


Q Run options 


l|message| 


;tin Options Help 


Pj Tools 


Figure 1.4 The VX-REXX Run menu, used to run a project under VX-REXX for debugging purposes. 




Arguments 


Working directory 


Abort 


Continue 


Figure 1.5 The Run Options command on the Options menu, which you can use to pass arguments to a 
project while it’s running under VX-REXX, as well as specify the default subdirectory for it to run in. 
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Making an .EXE File 

Once you’ve finished your program and are ready to turn it into an .EXE program, use 
the Make EXE File option from the Projects menu. This converts all the files associated 
with the currently loaded program into one .EXE program file. This program file can 
be executed on any OS/2 machine that has the VX-REXX runtime libraries installed. 

In addition to your .EXE file, anyone wanting to run your program will have to have 
a copy of the VROBJ.DLL file that comes with VX-REXX installed in a subdirectory in 
the libpath. Additionally, if you use database functions, users might also need a copy 
of the VXQE.DLL file that comes with VX-REXX. According to the VX-REXX online 
documentation, “. . . you are hereby granted a nonexclusive, royalty-free right to re¬ 
produce and distribute the VROBJ.DLL and VXQE.DLL files located in the VX-REXX 
directory provided that (a) they are distributed as part of and only with your software 
product; (b) you do not suppress, alter, or remove proprietary right notices contained 
therein; and (c) you indemnify, hold harmless, and defend Watcom and its suppliers 
from and against any claims or lawsuits, including attorney’s fees, that arise or result 
from the use or distribution of your software product.” So you can include copies of 
these two files with any software you write using VX-REXX. 

Getting Help 

VX-REXX provides context-sensitive help. Just press FI on any menu or object and 
a help screen will automatically pop up on the current topic. VX-REXX also comes 
with three electronic books you can access for additional help: VX-REXX Reference, 
VX-REXX Programmer’s Guide, and VXQE Library. The VX-REXX Programmer’s 
Guide contains the Getting Started and Programmer’s Guide portion of the printed 
manual, VX-REXX Reference contains the Reference portion and appendices of the 
printed manual, and VXQE Library describes using the Q+E database functions with 
VX-REXX. You can access these by clicking on their icons in the VX-REXX folder. 

A Sample Program 

You’ll understand VX-REXX better by creating a simple program. This program is 
called Pauselt, and can be found in the \EXAMPLES\PAUSEIT subdirectory of the 
CD-ROM that comes with this book. As a general rule, a program is contained in a sub¬ 
directory branching off the YEXAMPLES subdirectory that matches its name. Thus, 
ToDo-1 is stored in the \EXAMPLES\TODO-l subdirectory. When the subdirectory 
and program names don’t match, I’ll indicate where the program can be found. 

Pauselt displays a message in a Descriptive Text object and pauses until the user 
clicks on a PushButton object. Once the user clicks on the button, control is passed 
to the calling program. 

Begin by clicking on the Descriptive Text tool icon (top row of the tools, middle 
icon) and drawing the box on the screen. Exact size and placement aren’t crucial be¬ 
cause any of the elements can be moved around and sized anytime during the process. 
Next, click on the PushButton object icon (second row, left icon) and draw a Push- 
Button object on the screen. Figure 1.6 shows how the program currently looks. 
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Figure 1.6 A simple project consisting of one Descriptive Text object and one PushButton object. 


Note the dots on the screen in the work area. These are used to align the various 
elements as you’re working. They aren’t part of the final program. The program cur¬ 
rently fills only about !4 of the screen. The final program will be the same size as the 
work area that contains the dots. You can resize the work area using the standard 
OS/2 resizing tools, and the resulting program will be the same size. 

Note in Figure 1.6 that the PushButton object at the bottom of the work area has 
eight black squares around it. These are resizing handles that let you alter the size of 
the PushButton object. They work just like standard OS/2 resizing tools. Move the 
mouse cursor over one of these squares and it will turn into an arrow to indicate the 
directions you can drag that square to resize the object. The size squares let you go 
sideways, the top and bottom squares let you go up and down, and the corner 
squares let you move diagonally. Click and hold the right mouse cursor inside the ob¬ 
ject and you can move it to a new location. 

Now you’re ready to add text. Move the cursor over the Descriptive Text object 
and press the right mouse button to bring up the VX-REXX pop-up menu (see Fig¬ 
ure 1.7). You don’t have to select the Descriptive Text object first. In fact, if you look 
closely at Figure 1.7 you’ll see that the PushButton object is still selected because 
you can see the resizing squares. 

The VX-REXX pop-up menu always belongs to the object that the mouse cursor 
points to and not the selected object. You can see in Figure 1.7 that VX-REXX displays 
the type of object (Descriptive Text in this case) and its name (DT_1) on the line be¬ 
low the menu names. This is a quick way to tell which object the VX-REXX pop-up 
menu will modify. In this case you want to alter the properties of the Descriptive Text 
object, so click on Properties to bring up the property notebook, shown in Figure 1.8. 
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To alter the text, click on the Text tab to bring up the text page of the property 
notebook, as shown in Figure 1.9. Enter the text in the Caption block. If you press 
Return, the text will be immediately applied to the Descriptive Text object without 
waiting until you close the property notebook. Once you do close the property note¬ 
book, the program will look like Figure 1.10. 

Aligning the text at the top is a useful approach when you have a lot of text to dis¬ 
play. When you have only a single line to display, centering is a more attractive ap¬ 
proach. By opening the property notebook again and selecting the Style page, you 
can alter the vertical and horizontal justification of the text. In this case, select cen¬ 
tering for both. Figure 1.11 shows this. 

Next, you need to add text to the PushButton object, so bring up the VX-REXX 
pop-up menu, open its property notebook, and enter the text under the Text tab. 
Now you need to add the code to terminate the program when the user clicks on the 
PushButton object. To do that, bring up the VX-REXX pop-up menu, select Events, 
and then Click to bring up a REXX subroutine containing the following lines: 

/*:VRX */ 

PB_l_Click: 

return 


The first line is a comment that the VX-REXX editor uses to track the subroutines. 
The second line first identifies the object (PB_1 or the first PushButton object added 
to the program) and then the event, Click. The final return is added automatically. 
Don’t change any of this. 



.... ,V/- , 


BltiSEff ;(£h6S2\¥k g 


Pi VX-REXX 


Color 


Project Jools Windows Run 0 


Object: , DT_T [DescriptiveText] 


General 


Caption 


S/Press .On Button Below 


<default> 


Properties for DTJ [DescriptiveText] 


Figure 1.9 Changing the text in the property notebook for the Descriptive Text object. 
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Figure 1.10 The default placement of text in the Descriptive Text object, which isn’t very attractive in 
this example. 
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Figure 1.11 The text display properties are changed in the property notebook for the Descriptive 
Text object. 
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When the user clicks on this button, you want the program to terminate. There is 
a system-generated Quit subroutine for this purpose, so all you have to add is a CALL 
Quit command. Figure 1.12 shows this. Double-click on the OS/2 close button at the 
top left of the window to close and return to the program window. 

At this point, I should make a note on capitalization. VX-REXX shows REXX 
commands in all lowercase, as you can see with the Return command. I prefer to 
have REXX commands in all uppercase, but in the VX-REXX programs I write I 
don’t change any commands automatically added by VX-REXX. The publisher’s 
standard is to show commands capitalized so they stand out in the book rather 
than being seen as part of the text. For the text of this book, I will follow this con¬ 
vention. 

As a last step, you need to align the two objects relative to each other. To do 
that, use the pointer icon (top row of the tools, left icon), click and hold with the 
left mouse button at the top left corner of the area containing the objects, and 
drag the cursor so all the objects to align are selected. Then release the left mouse 
button and click with the right mouse button inside this area to bring up the VX- 
REXX pop-up menu. From here, select the Align option and the type of alignment 
you want. Here you want to center them vertically—the fourth option from the 
top (see Figure 1.13). Note that both objects have resizing squares, indicating 
they’re both selected. 

Figure 1.14 shows the final program as it appears in VX-REXX. By selecting Make 
EXE File from the Project menu, you’re ready to create a stand-alone program. Fig¬ 
ure 1.15 shows the final program running under OS/2. Note that the dots and all the 
VX-REXX items have been removed. 
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Figure 1 .12 Adding code to the Click event of the PushButton object. 
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Figure 1.14 How the final project looks in VX-REXX. 
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Figure 1.15 The final program 
while running. 


The total time to create this program was about 20 minutes. To write even this 
simple program in REXX would have taken much longer. Since the program was to¬ 
tally devoted to the user interface, you had to add only one line of REXX code—the 
CALL Quit line—to the click event of the single PushButton object. 


Drag-and-Drop Programming 

Most people think of programming as a programmer sitting at a keyboard and typing 
computer code. That works with VX-REXX and it’s how I write much of my code, but 
there’s an easier way, especially if you have trouble remembering all the properties, 
methods, and so on that VX-REXX offers. That easier way is drag-and-drop pro¬ 
gramming. With drag-and-drop programming, you drag the object you’re writing 
code about to the editor and drop it into your code. Then VX-REXX displays a menu 
of the available things to do and you pick from the menu. 

Before I can illustrate this, you need a sample program to work with. Keep in mind 
that my purpose here is to illustrate the editor and drag-and-drop programming, not 
the programming concepts themselves. You’ll understand these as you work through 
the book, but they might be confusing now. Figure 1.16 shows ShowEdit, a sample 
program that will simply illustrate the editor. There will be four objects on the 
screen. In order, from top to bottom, they are: 

* 

EF_1. This is an EntryField object. When the program is running, you can enter text 
into this field. 

PB_1. This is a PushButton object. When the program is running, the user can 
click on it to “push” the button. VX-REXX will then run the code you’ve associ¬ 
ated with pushing the button. In this sample program, pushing the button will 
take the text that was entered in the EntryField object and put it into the De¬ 
scriptive Text object. 
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DT_1. This is a Descriptive Text object. When the program is running, it displays 
text. That text can be preconfigured or inserted while the program is running. In this 
case, the text will come from the EntryField object. 

PB_1. This is another PushButton object. Click on this button to exit the program. 

Since clicking on PB_1 is the event that will take the EF_1 text and put it into 
DT_1, you need to click on PB_1 with the right mouse button to bring up a list of pos¬ 
sible actions, shown in Figure 1.17. To define a program to an event, click on Event 
to bring up a list of events, shown in Figure 1.18. To have the program do something 
when the user clicks on PB_1, select Click to program the click event. This brings up 
the VX-REXX editor ready to accept code for the Click event. 

The top line is a REXX comment that the editor adds to identify the beginning of 
a section. The second line is the name of the routine. It begins with the name of the 
object, PB_1, followed by an underscore and the name of the event. If you were to 
rename the object using its property notebook, this name would automatically be 
changed. The last line is the Return that REXX uses to mark the end of a subroutine. 

At this point you could begin typing in REXX and VX-REXX code, which is what I 
normally do. For what you want to accomplish, however, drag-and-drop program¬ 
ming is easier. But before you can use drag-and-drop programming, you must be able 
to see both the object of interest and the editor. This might require you to resize one 
or both windows and move them around. 
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Figure 1.16 The ShowEdit user interface before any code is added. The four objects on the screen from 
top to bottom, are EF_1, PB_1, DT_1, and PB_2. 
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Figure 1.18 Clicking on Events generates a list of the events associated with PB_1 
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The first thing you want this code to do is read the contents of EF_1, so click on 
EF_1 with the right mouse button and hold that button down while dragging it 
into the editor. While the mouse cursor remains in the VX-REXX window, EF_1 
will move around. Once the mouse cursor moves outside the VX-REXX window, 
two things will happen. First, EF_1 will pop back to its original location and a line 
will connect EF_1 with the mouse cursor. Move this line into the editor to initiate 
drag-and-drop programming. 

Once you release the mouse button, a Select An Action box will pop up listing all 
the actions you can perform on that object. For this program, you need to get a value 
from EF_1, so scroll down to the Get Property section and double-click on Value 
(see Figure 1.19). The appropriate code is automatically inserted in the editor, as 
shown in Figure 1.20. 

Once the program has the value from EF_1, you want the value erased from EF_1, 
so draw another line from EF_1 to the editor to bring up the Select An Action box. 
This time select Value from Set Property to put another value into EF_1. This brings 
up the dialog box shown in Figure 1.21, in which to enter the value. You want a blank 
value, so enter two quote marks, with nothing between them in the value field and 
click on OK. 

Note in the code that the value from EF_1 is stored in the variable named Value. 
You want to insert this value into DT_1, so draw a line from DT_1 to the editor. This 
time, select Caption under Set Property to change the caption of DT_1. Again, this 
brings up a dialog box. Since the text is stored in a variable, uncheck the Quoted 
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Figure 1.19 Clicking on EF_1 with the right mouse button and dragging it into the editor generates the 
Select an Action box to initiate drag-and-drop programming. 
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Figure 1.20 Once you select an action for the Select an Action box, the code is automatically inserted into 
the editor. 
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String box and type the variable name (Value) in the field and click on OK. The fin¬ 
ished code is shown in Figure 1.22. 

Except for programming the Quit button, PB_2, this application is finished. To 
program the Quit button, enter CALL Quit in its Click event. You just wrote an entire 
application using a mouse for all but one quick line of code. Figure 1.23 shows the 
program running. 

However, many of your programs are going to require extensive REXX coding. 
When that happens, VX-REXX has a feature to help you write this code. For exam¬ 
ple, let’s take the string that gets taken from EF_1 and use only the right 25 charac¬ 
ters. You might recall that the REXX Left function does this, but even so you might 
not remember its syntax. To get help writing this code, move the cursor to the point 
where you want the code inserted and select Insert Code... from the Edit menu. This 
brings up the EntryField box, shown in Figure 1.24. 

From this EntryField box, select the function you want REXX to perform. The 
list is surprisingly complete. In this case you want to get the leftmost characters 
from a string. This requires additional information, which VX-REXX requests in 
the dialog box shown in Figure 1.25. Once this information is completed, the er¬ 
ror-free code is inserted into your program at the cursor position. VX-REXX uses 
the name Newstring for the variable, but I edited that to restore the string to the 
Value variable. Note that, while you can’t see it in the screen shot (because I used 
a space), a pad character must be entered into the appropriate entry field in Fig¬ 
ure 1.25. 

While VX-REXX cannot write all your REXX code for you, it does a good job of re¬ 
membering syntax and of writing the fairly simple code. 



Figure 1.22 The finished code for PB_1, in the ShowEdit program. 
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Figure 1.24 Selecting Insert Code... from the Edit menu in the VX-REXX editor, which brings up an En- 
tryField list where you can select the type of code you want to insert. 
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String: 


Length: 


Pad: 


OK 



Figure 1.25 Selecting “Get the 
leftmost characters from a string” 
brings up a dialog box where you 
can fill in the information VX- 
REXX needs. 


Summary 


This chapter provides a review of how to use the various aspects of the VX-REXX 
program and shows how to create a simple program using VX-REXX. 











Chapter 

2 

Descriptive Text Objects 


In Chapter 1, you saw how to use a Descriptive Text object to display static text on 
the screen. That is, by far, the most common use for a Descriptive Text object. How¬ 
ever, it’s also useful for displaying messages that need to change (error messages, for 
example) and even text from a file that you want the user to be able to view but not 
modify. This chapter will continue to show you how to use Descriptive Text objects 
in your programs by describing two example programs: Message and Line-1. 

Let’s take a minute first to discuss objects in general. Objects are the basic building 
blocks of all VX-REXX programs. An object consists of its properties (its characteris¬ 
tics and data), its methods (the actions it can perform), and the events it responds 
to. The properties, methods, and events of each object are different and it’s up to the 
programmer to select the appropriate object. These are summarized in Chapter 22. 


Message 

The Message program is designed to be called from a batch file to display an error 
message and give the user two alternatives: Continue and Abort. The message is 
taken from the command line and displayed in a Descriptive Text object. After dis¬ 
playing the text, the program waits for the user to click on either PushButton object. 
If the Continue button is clicked, the program will supply a return code (also called 
an errorlevel) of zero. If the Abort button is clicked, the program will supply a return 
code of one. It’s up to the batch file to respond based on these return codes. 

User interface 

The program should have one Descriptive Text object and two PushButton objects. 
The Continue and Abort PushButton objects should be the same size, and the easiest 
way to accomplish this is to create one and copy it to the other. The first step is to cre¬ 
ate either of the buttons. Next, select the button and bring up the VX-REXX pop-up 
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menu by clicking on the right mouse button. Then use the Copy command to copy 
the button into the paste buffer, shown in Figure 2.1. After that, bring up the VX- 
REXX pop-up menu again and use the Paste command to create a copy of the button. 

You might notice in Figure 2.1 that the VX-REXX pop-up menu has a Duplicate op¬ 
tion. There is a crucial difference between using the Copy/Paste approach and Du¬ 
plicate approach for copying objects. Using Copy/Paste, the new object has a new 
name, as you can see by loading Message and moving the mouse cursor over the two 
buttons. One is named PB_1 and the other PB_2. Using the Duplicate approach, both 
the original and duplicate object have the same name. For now, use the Copy/Paste 
approach. Later, you’ll see that the Duplicate approach can be even more powerful. 


Obtaining text from the command line 

Figure 2.2 shows the final user interface for this program. The two buttons have ti¬ 
tles on them, but the Descriptive Text object doesn’t. Since that text is coming from 
the command line, it isn’t available during design—only at run time. The code to take 
the text from the command line and use it in the Descriptive Text object is: 

IF InitArgs.0 = 0 THEN CALL VRSet "DT_1", "Caption", "No Message" 

ELSE CALL VRSet "DT_1", "Caption", InitArgs.1 
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Figure 2.1 Copying an object using the VX-REXX pop-up menu. 
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Figure 2.2 The final user interface for the Message project. 


This code is added to the bottom of the Init (Initialize) section so it’s processed prior 
to displaying the Descriptive Text object. Therefore, the text will be available to dis¬ 
play in the Descriptive Text object. 

The InitArgs.O stem variable is created automatically by VX-REXX, and it stores 
the number of arguments passed to the program. Due to the way REXX handles ar¬ 
guments, all the text passed to a program is treated as a single argument when the 
program is called from the command line. It’s only when a program is called by an¬ 
other REXX program or when one subroutine calls another that there can be multi¬ 
ple arguments. In that case, each argument must be separated by a comma. For 
more information, I refer you to my Writing OS/2 REXX Programs book or the OS/2 
online documentation for REXX. 

When InitArgs.O is zero, no arguments were passed to Message, so the default 
string of No Message is used. When InitArgs.O is one, one argument was passed to 
Message and that argument is stored in the InitArgs.l stem variable. When that is the 
case, the second line of the program uses this string as the message. 

There’s a bug in version 1.x of VX-REXX that causes InitArgs.O to be set to one 
when a program is run from the command line but not passed any arguments. If 
you’re using this version of VX-REXX, you must test for initArgs. 1=" " rather 
than InitArgs . 0 = 0 to avoid this bug. 

The VRSet function is used to control object properties at run time. In this case, it 
sets the caption of DT_1 (the single Descriptive Text object) to either the No Mes¬ 
sage string or the string passed on the command line. 
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REXX coding 

Since clicking on either PushButton object causes the program to terminate, both but¬ 
tons needed a CALL Quit command in their Click section. Additionally, the program is 
to return different return codes depending on which button is clicked, so a variable is 
created in each Click section. The PB_1 (Continue) button has an ExitCode=0 com¬ 
mand, while the PB_2 (Abort) button has an ExitCode=l command. The RETURN 0 
command in the Fin (Finish) section is replaced with a RETURN ExitCode command. 

While the Click section of a PushButton object can be reached with the VX-REXX 
pop-up menu, the Fin section cannot. For that, you need the floating Section menu, 
as shown in Figure 2.3. This menu lists all the sections, allows you to add new sec¬ 
tions, and lets you delete existing sections. Since it’s a floating menu, you can drag it 
to any location on the screen to keep it out of your way. Each time you load a pro¬ 
gram, it remembers the position of the menu and restores it to its proper position. 
Activate the menu by pressing the F6 key or using the Section List option of the Win¬ 
dows menu. To edit a particular section, simply double-click on its name. 



VX-REXX — MESSAGE (C:\OS2WXREXX\EXAMPLESVMESSAGE\MESSAG 


DT_1 .Context-Menu 


Project Tools Win dows Run Options Help 


Pj Tools 


b[ ©] : a 


Continue 


Abort 


P| Sections — message; 

Section 


Figure 2.3 The Section menu of VX-REXX. 
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Figure 2.4 Running the Message project. Note that text has been 
taken from the command line and used in the Descriptive Text object. 


Running the program 

Figure 2.4 shows Message running using a message passed to it from the command 
line. After compiling Message, you can see it called from a standard REXX program 
using the SHOWTEXT.CMD REXX program that’s included in \EXAMPLES\MES- 
SAGE subdirectory of the included CD-ROM. 


Line-1 

The Line-1 program reads an ASCII file into memory and displays the first 15 lines of 
the file on the screen in 15 individual Descriptive Text objects. If the file is too large 
to fit in the initial display, the program allows the user to scroll through the file using 
a Forwards and Backwards PushButton object. There’s also a Quit PushButton ob¬ 
ject to exit the program. The program takes the name of the file from the command 
line. It’s an example program, so it doesn’t perform any error-checking to make sure 
the file exists, to make sure the file is an ASCII file, or to make sure the individual 
lines “fit” on the display lines without having to wrap them to another line. 

This will be the first program in this book to have a significant amount of REXX 
code. Nevertheless, the majority of this code will be devoted to processing informa¬ 
tion for the VX-REXX program rather than actual REXX manipulations. 

User interface 

The program is to have 15 Descriptive Text objects for displaying the text and an ad¬ 
ditional Descriptive Text object for displaying error messages. In addition, it will 
need three PushButton objects for scrolling forwards and backwards and for quitting 
the program. 

In order to display the maximum amount of text, make the VX-REXX screen as 
wide as possible. Do this by moving the cursor to the border of the display area 
where it will change into an arrow, clicking with the left button, and dragging the 
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work area out to the size you want. This will cover up the tool icons, so you can turn 
them off and select your tools using the menu at the top. 

Once the work area has been enlarged, the next step is to add the 15 Descriptive 
Text objects used to display the file, numbered DT_1 to DT_15. The Descriptive Text 
object for the error message will be added later. These objects need to be highly cus¬ 
tomized and identical, so the best approach is to create a single Descriptive Text ob¬ 
ject, customize it, then Copy and Paste to get the remaining 14. 

The initial Descriptive Text object should be as wide as the screen and slightly 
higher than a line of text. Set the background color to white and the foreground 
color to black. Under the Style tab of the Properties Notebook, set the vertical jus¬ 
tification to center and remove the click beside the WordBreak box. The centered 
vertical justification prevents a portion of the second line from showing when a 
single line is too long for the screen and wraps to the next line. Normally, the 
WordBreak setting doesn’t matter because it simply controls where a line is bro¬ 
ken when it’s too long for the screen. However, if you use the resulting program to 
display your CONFIG.SYS file, then much of the lines that have only one space 
just after the SET command won’t show. Turning off WordBreak prevents this by 
breaking the line at the end of the Descriptive Text object without regard for 
spaces. 

Once the first Descriptive Text object is ready, use Copy and Paste from the VX- 
REXX pop-up menu to create 14 more copies and place them into a large square. Make 
sure they’re in order, with DT_1 at the top and DT_15 at the bottom. After this, add 
the Forwards, Backwards, and Quit PushButton objects and the final Descriptive Text 


VK-REXX — tiME-1 (C:\dS2WXREXX\EXAMPLES\LINE-t\LINE-1.VRP 


Project Tools Windows Run Options Help 
Object: ’DTJ5’ [DescriptiveText] 


ill 


Scroti Forwards \ l Scroll Backwards 


Quit Program 


Figure 2.5 The final version of the user interface for the Line-1 project. 
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object for the error messages. For descriptive purposes, I named this final Descriptive 
Text object DT_ErrorMessage. Figure 2.5 shows the final version of the user interface. 


Other REXX coding 

The Init section needs only three additional lines to handle this program. They are: 


File = InitArgs.l 

CALL GetData 

LineNumber = BuildScreen(1) 

The first line stores the name of the file the user enters on the command line to a 
variable name. To make this an operational program, this line would need error¬ 
checking to make sure the user entered a filename and that the filename exists. The 
second line calls a subroutine to read in the data. The third line calls a subroutine as 
a function to display the initial screen. The number 1 being passed to this function 
tells it to start displaying the screen at the first line. 

The GetData subroutine is used to read in the lines of text from the ASCII file en¬ 
tered on the command line. That subroutine is as follows: 


IF InitArgs.0 = 0 THEN DO 
Count = 1 
Line.O = 1 

Line.O = "No File Specified on Command Line 
RETURN 

END 

Line. = "" 

DO WHILE LINES(File) 

Count = Count + 1 

Line.Count = Lineln(File) 

END 

Line.0 = Count 
Variable = LineOut(File) 


The first six lines handle the situation of the user not entering a filename. The 
next line initializes the stem variable. The next four lines process the file, storing 
each line to its own entry in the stem variable. The next-to-last line stores the 
number of lines to the Line.O variable, and the last line is a REXX command to 
close the file. 

The BuildScreen subroutine stores the appropriate lines of text to the appropriate 
Descriptive Text objects. This is the heart of the program. It is both shown and de¬ 
scribed in detail in Figure 2.6. 

The Click event for both the Forwards and Backwards PushButton objects begins 
with a call to the ResetErrorMessage subroutine to clear out the old error message 
and then a call to either the Forwards or Backwards subroutine to handle the actual 
scrolling. The ResetErrorMessage subroutine is: 

ResetErrorMessage: 

CALL VRSet "DT_ErrorMessage", "Visible", 0 
CALL VRSet "DT_ErrorMessage", "Caption", "" 

return 
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Explanation 

BuildScreen: 

Name of the subroutine. 

PROCEDURE EXPOSE Line. Screen. 

Hide all the variables except the 
stem variables Line, and Screen. 
This also hides all the variables 
created by this subroutine 
except these two stem variables. 

StartPoint = Arg(1) 

The subroutine requires a start¬ 
ing point to be passed to it and it 
reads this in as the first argu¬ 
ment. 

DO I - 1 TO 15 “ 

Loop through the fifteen vari¬ 
ables used to store the text for 
the screen to store a space to 
them. 

Screen.I = " " 

Store a single space to the vari¬ 
able so the variable will not be 
undefined and display its name. 

END 

End of the DO I = 1 TO 15 
loop. 

DO I = 1 TO 15 

Loop through the fifteen vari¬ 
ables used to store the text for 
the screen to store text to them. 

LineToUse = StartPoint +1-1 

Create a variable to indicate 
which line in the Line, stem 
variable is to be stored to the 
current line on the screen. One 
must be subtracted from the 
StartPoint variable, so the 
display starts with the StartPoint 
line and not the one after it. 

IF LineToUse <= Line.O THEN 

Screen.I - Line.LineToUse 

If the line to use has not exceed¬ 
ed the total number of lines that 
were read in, store that line to 
the screen variable. If the end of 
the file is reached, the single 
space stored to this variable in 
the loop above is not replaced. 

END 

End of the second DO I = 1 TO 

15 loop. 

DO I = 1 TO 15 

Loop through the fifteen vari¬ 
ables used to store the text for 
the screen to set them into the 
appropriate Descriptive Text 
abject. 


Figure 2.6 The BuildScreen subroutine is crucial to Idle operation of the Line-1 project. 








Descriptive Text Objects 29 


VX-Rexx Code- 

Explanation 

ToAdd = "DT_" || I 

Create a variable containing the 
name of the Descriptive Text 
object to use. 

CALL VRSet ToAdd, "Caption", Screen.I 

Store a line of text to the caption 
of the Descriptive Text object. 

END 

■ 

EndNumber = MIN(StartPoint + 14, Line.O) 

Compute the line number of the 
last line being displayed. This 
will be either fourteen lines after 
the first line displayed or the last 
line of the file, whichever is 
smaller. 

return EndNumber 

Return the last line being dis¬ 
played. 


Figure 2.6 Continued. 


All it does is make the Descriptive Text object invisible and reset its caption to null. 
The Forwards subroutine is: 


IF LineNumber = Line.O THEN 
DO 

CALL VRSet "DT_ErrorMessage", 
CALL VRSet "DT_ErrorMessage", 
CALL Beep 500, 500 
RETURN 

END 

IF Line.O <= 15 THEN 
DO 

CALL VRSet "DT_ErrorMessage", 
CALL VRSet "DT_ErrorMessage", 
CALL Beep 500, 500 
RETURN 

END 


"Visible", 1 

"Caption", "At End Of File 


"Visible", 1 

"Caption", "All Records Displayed" 


LineNumber = BuiIdScreen(LineNumber) 
return 


The first IF test and associated DO block handle the case where the number of the 
last line (LineNumber) equals the number of lines in the file (Line.O). In this case it 
creates an error message, makes the error Descriptive Text object visible, beeps the 
speaker, and returns because no more forward scrolling is possible. The second IF 
test and associated DO block handle the special case when all the text can be dis¬ 
played in a single screen because there are 15 or fewer lines. Since no scrolling is 
possible, it displays an error message, beeps, and returns. 

The final line calls the BuildScreen function to actually scroll the screen forward, 
when possible. In order to have the last line of the current screen be the first line of 
the next screen, it passes that line number as the starting position for the next screen. 
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The Backwards subroutine has the same first two sections as the Forwards sub¬ 
routine, except that the first one checks to see if the number of the last line 
(LineNumber) is less than 15—indicating it’s showing the first screen of data— 
rather than being equal to the last line in the file. The actual scrolling portion is dif¬ 
ferent, however, as shown in the following: 


ToStart = MAX(1, LineNumber-28) 
LineNumber = BuildScreen(ToStart) 
DROP ToStart 


Since the LineNumber variable stores the last line on the screen and you want to 
scroll backwards, you must reduce this number. Subtracting 14 from the number 
yields the first line currently on the screen, so passing LineNumber-14 would regen¬ 
erate the current screen. To scroll back 14 lines so the first line of the current screen 
is the last line of the next screen, you must pass it LineNumber-14-14 or LineNum- 
ber-28. The first line in the previous section of code creates this variable while mak¬ 
ing sure it doesn’t attempt to scroll back past the beginning of the file, the second 
passes it to the BuildScreen function, and the third drops the variable. 


Running the program 

Figure 2.7 shows the Line-1 program running and displaying my CONFIG.SYS file. 
Note how the last line of the display has only one space near the beginning. If this 
line were too long to be displayed and the word Break option were turned on, noth¬ 
ing after this space would be visible. Also note that it displays a status message in the 
bottom right corner. 


DEVICE=F:\0S2\C0N.SYS (3,03E8,5) 

DEVICE=F:\0S2SMD0SWC0M.SYS 

CODEPAGE=437,850 

DEVINF0=KBD,US,F:\0S2NKEYB0ARD.DCP 
SET V10_85'MA=DEVICE(BVHVGA,BVH8514A) 

REN DEVICE and RUN statements from your older CONFIG.SYS 

REN IFS=F:\0S2\CDFS.IFS /Q 

BASEDEV=0S2SCSI.DND 

DEVINF0=SCR,BGA,F:\0S2WI0TBL.DCP 

SET VIDE0_DE ViCES=VIO_8514 A 

DEVICE=F:\0S2\ND0S\VVGA.SYS 

DEVICE=F:\OS2\MDOSW8514A.SYS 

DEVICE=F:\OS2\OS2CDROM.DMD /Q 

IFS=F:\0S2\CDFS.IFS /Q 

SET VXREXX=C:\0S2WXREXX 




Scroll Forwards ~j j Scroll Backwards [ [ Quit Program 


Figure 2.7 The Line-1 program running and displaying a portion of a CONFIG.SYS file. 
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Summary 


I should point out that there are much easier ways to display an ASCII file than us¬ 
ing 15 Descriptive Text objects, and some of these will be covered later in this book. 
The purpose of Line-1 is simply to illustrate Descriptive Text objects rather than to 
suggest how to display files. 


This chapter continues the discussion begun in Chapter 1 of using Descriptive Text 
objects in a program for displaying text. The Message program takes a single line of 
text from the command line and displays it in a Descriptive Text object. The Line-1 
program displays an entire file in 15 single-line Descriptive Text objects, and allows 
the user to scroll through the file if it’s too long to fit on one screen. 




Chapter 

3 

Dressing Up Your Windows 


Now that you’ve seen how to create simple programs, I need to spend some time ex¬ 
plaining how to “dress up” programs before you look at adding more objects to your 
programs. 

Programs run in the windows you create when you design a program. The window 
is the area that surrounds the objects as you create the program. As you’ll see, by 
changing the appearance of this window you improve the appearance of the overall 
program. 


Pauseft 


Figure 3.1 shows the Pauselt program running with the System menu activated. 
Note that the name in the border at the top left is simply the name of the program— 
PAUSEIT.EXE. Since you can exit Pauselt by clicking on the OK button, this menu 
isn’t necessary. By way of example, you’ll make several changes to the configuration 
of Pauselt. So the original version of Pauselt isn’t changed, this modified version will 
be called Pauselt2. 

You can change the appearance and operation of a window the same way as any 
other object, by clicking on it with the right mouse button and bringing up its prop¬ 
erty notebook. You must make sure the mouse pointer is on the window and not on 
an object. In Figure 3.2,1 changed the title shown in the title bar by using the Text 
tab of the property notebook. This is also the title that will show up in the OS/2 win¬ 
dow list when you press Ctrl-Esc. 

Next, use the Frame tab to hide the System menu and select MinimizeButton and 
MaximizeButton to enable minimize and maximize buttons. This is shown in Figure 
3.3. Figure 3.4 shows the resulting program running. While there’s no System menu 
to close the program, the user can still bypass the program and close the program 
with OS/2 by bringing up the OS/2 window list with Ctrl-Esc, clicking the right 
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Restore 

' A1I+F5 

Move 

Alt+F7 

Size 

Alt+F8 

Minimize 

Ait*F3 

Maximize 

Att+FI8 

Hide 

Alt+F11 

Close 

Alt+F4 


Window list CtrWEsc 


m Below To Continue 


OK 


Figure 3.1 Pauselt running with its system menu activated. 



Figure 3.2 Changing the title under the Text tab. 
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Figure 3.3 Hiding the system menu under the Frame tab. Also note that MaximizeButton and Minimize- 
Button have been activated. 



Click On The Button Below To Continue 



Figure 3.4 Running Pauselt with changes. 
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Figure 3.5 How Pauselt looks after being maximized. 


mouse button over the name of the program, and selecting Close. There’s no way to 
avoid this, nor would you want to in most cases. 

A minimize button allows the user to reduce the program to an icon and work on 
something else; most programs should have this button. A maximize button allows 
the user to increase the size of the program up to full screen. However, this creates 
a problem for the program since the original design calls for a specific location and 
size for each object relative to a fixed window size. As Figure 3.5 shows, that can lead 
to unusual screens if the user maximizes the screen. 

You can partially compensate for this by changing the LayoutStyle property to 
SimpleDialog on the Style tab of the window property notebook. Alternatively, you 
can have the program reposition or resize the objects in the Resize event. Or you can 
just not enable a maximize button. Doing this doesn’t prevent a user from returning 
the program to its original size after minimizing the program. 


M@ssage2 

With Message running, the program that called it might depend on the return code it 
provides to take some action. For this reason, you want to avoid having the user use 
the System menu to close the program. You can make that change just as you did for 
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Pauselt. This modified version is stored in \EXAMPLES\MESSAGE2. You can also 
change the title and add a minimize button. No maximize button will be added to this 
version. 

Now there are two additional properties you need to add to Message. The first is a 
default button. This is the button the program will assume was pushed if the Return 
key is pressed while none of the buttons are selected. The second is the Cancel but¬ 
ton. This is the button the program will assume was pushed if the Escape key is 
pressed. For this example, you want the Abort button to have both these properties; 
Figure 3.6 shows creating them in its property notebook. These are toggles , which 
means that when one button is given this property, VX-REXX automatically removes 
the property from any other button. So only one button can have the default prop¬ 
erty and only one button can have the cancel property. 

Finally, change the background color to red to draw more attention to the program 
while it’s running. Figure 3.7 shows the resulting program. 


Summary 

By changing the properties of the window that surrounds the objects, you can 
change the appearance of the entire program. With Pauselt, you changed the title 
bar, removed the system menu and added a minimize and maximize button. With 
Message, you changed the title bar, removed the System menu, added a minimize 
button, and made Abort the default and Cancel buttons. 



VX-REXX — MESSAGE2 (C:\OS2WXREXX\EXAMPLES\MESSAGE2\MESS, 


Project Tools Windows Run Options Help 
DescriptiveT ext _ 


Message by Ronny Richardson 


[ ° lj 

Properties for PB„2lPusbBu tton] 


Event 
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... . . . 


2 Border 

BorderColor 
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S3 Cancel 
12 Default 
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Figure 3.6 Setting the default and cancel properties for the Abort button of message under the Style tab. 
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Figure 3.7 The modified Message running. 



Chapter 

4 


PushButton Objects 


A PushButton object starts the action associated with the button. It will end up be¬ 
ing one of your most common design elements, as you’ve already seen with some of 
the example programs from the earlier chapters. There are three ways to press a 
PushButton object: 

1. Click on it with the left mouse button. 

2. Press the spacebar while the PushButton object has input focus. OS/2 allows you 
to use the cursor-movement keys to switch between the various objects within a 
window and give each one, in turn, input focus. When an object has input focus, 
it has a slightly darker outline than the other objects. 

3. Press Return while the PushButton object has input focus. 

Additionally, one PushButton object can be designated as the Cancel button and an¬ 
other PushButton object (or the same one) can be designated as the default button, 
as discussed in Chapter 3. These buttons are “pushed” when you press Escape or Re¬ 
turn, respectively, without any PushButton object having focus. 


Music 

The Music program plays a note each time a key is pressed. The interface looks like 
a miniature piano with the keys C through G and A through C on various PushBut¬ 
ton objects. 


Interface 


The interface to Music is very simple—eight identical PushButton objects for the dif¬ 
ferent notes and a smaller Quit button to exit the program. Figure 4.1 shows the user 
interface for Music. 
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Figure 4.1 The user interface for the Music program. 


REXX coding 

The notes in the scale are C, D, E, F, G, A, B, and C. Their frequencies in Hertz are 
262, 294, 330, 349, 392, 440, 494, and 524 respectively. The REXX code to play a 
note is: 


CALL BEEP frequency, duration 


where duration is the length of the note in milliseconds. For this program I used 250 
millis econds for each note. So this single line with the appropriate frequency is used 
as the Click event for each PushButton object. The Quit button simply has CALL 
Quit as its Click event. 


Music-2 

Like Music, Music-2 plays a note each time a key is pressed, and the keys C-G and 
A-C are on various PushButton objects. 


Interface 


Music requires eight different keys playing eight different notes. This isn’t difficult to 
program since the code for each note is only a single line. However, if the code were 
longer, it would be more difficult to build the interface. Often you want several keys 
to perform the same action with only a very slight difference between them, as is the 
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case with Music-2. When this is the case, duplicating the same key is a better ap¬ 
proach, which is what we’ll do with Music-2. 

Start by creating a single music key and giving it the proper appearance. In¬ 
stead of having it play a note in its Click event, have it call the MakeMusic sub¬ 
routine. After that, you can create the Quit button and configure the window. 
Figure 4.2 shows this. Once this is finished, duplicate the music PushButton ob¬ 
ject seven times using the Duplicate option of the VX-REXX pop-up menu, as 
shown in Figure 4.3. 

These duplicate PushButton objects will have the same name as the original Push- 
Button object, or PB_1 in the example. They share common code and, if you change 
the Click event for any of the PushButton objects, it will automatically change for all 
the duplicate PushButton objects. To complete the example, go to each PushButton 
object and change its caption, as shown in Figure 4.4. While the PushButton objects 
share a common name and code, VX-REXX allows them to have a unique caption, 
color, and size. The program uses these captions to figure out which copy of the 
PushButton object was pressed and to respond accordingly. 

REXX coding 

The program needs to know which note corresponds to which PushButton object 
caption. The following code in the Init section begins to take care of that by creating 
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Figure 4.2 The Music-2 program with just a PushButton object. 
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Figure 4.3 Using the duplicate option on the VX-REXX pop-up menu to make copies of the single 
PushButton object, where the copies have the same name as the original. 
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Figure 4.4 The final interface for the Music-2 program. 
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a stem variable with the same stem as the captions and containing the appropriate 


frequency: 


Music.C = 

262 

Music. D = 

294 

Music. E = 

330 

Music. F = 

349 

Music. G = 

392 

Music. A = 

440 

Music. B = 

494 

Music.C2 = 

= 524 


Next, create the MakeMusic section, as follows: 


MakeMusic: 

Caption = VRGet(VRInfo("Object"), "Caption") 
CALL BEEP Music.Caption, 250 
return 


The second line reads the caption of the key that was pressed and stores it to the 
variable called Caption. The next line beeps the speaker using the stem variable Mu¬ 
sic. Caption to play at the appropriate frequency. 

Music and Music-2 are simple examples. Although Music-2 takes more code to use 
duplicate PushButton objects than Music does to use individual PushButton objects, 
when the program is more complex and there are more PushButton objects the use 
of duplicate PushButton objects can be much simpler, as the next example illustrates. 


Keyboard 

Keyboard presents a simulated keyboard on the screen. The user types by using the 
mouse cursor to click on buttons on the screen. The typed letters then appear on the 
screen above the keyboard. The program automatically handles word wrap on screen 
so lines are always broken in between words. As the screen fills up, the text scrolls off 
the screen. To press a shifted key, click on the Shift key first. The Shift key is “sticky,” 
so the next letter typed will be shifted even though the Shift key isn’t still held down. 
After a single shifted key is entered, the Shift key automatically returns to the un¬ 
shifted state. Text cannot be saved or printed, but it would be a simple addition. 

Warning: Due to the large amount of information on the screen, if you have a VGA 
monitor you’ll have trouble fitting all of the keyboard program on the screen. 


Interface 


The “keyboard” will consist of a number of duplicate PushButton objects for each of 
the letters, numbers, and symbols. The letters will have their uppercase value as a 
caption while the numbers and symbols will have their shifted value first and then 
their unshifted value second. Since letters will have a single character caption and 
everything else a two-character caption, it will be easy for the program to tell the two 
types of keys apart and reach differently. The two Shift keys are handled with a sep¬ 
arate PushButton object. 
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Figure 4.5 shows the screen with a single PushButton object on it. This PushBut- 
ton object has been renamed to PB_Key. It has been sized to the appropriate size and 
formatted the way you want most of the final keys to look. Its Click event simply calls 
the GetKeyStroke subroutine. Once this PushButton object is ready, you can repeat¬ 
edly duplicate it to form the first row of keys. Of course, once the row is ready, all the 
captions have to be manually changed one at a time, as shown in Figure 4.6. 

You could continue in this fashion, duplicating one key at a time, but there’s a 
quicker way. By selecting the entire row of keys and selecting Duplicate, you can du¬ 
plicate the entire row at once. The entire row will be selected, so you can drag all of 
it into place at once. As an additional bonus, each PushButton object on the dupli¬ 
cated row will share the same relative position as the PushButton objects in the orig¬ 
inal row, so if we move the row all at once you don’t have to worry about aligning the 
new row (see Figure 4.7). 

On a keyboard, each successive row has more keys, so you must add a key to the 
new row. Having duplicated the row all at once doesn’t interfere with duplicating a 
single PushButton object on the end of the row. This longer row can then be dupli¬ 
cated to form the next row, and so on until the entire keyboard is finished. 

Figure 4.8 shows the final keyboard with all the PB_Keys duplicate PushButton 
objects. Note that the spacebar has been resized to look more like a normal spacebar. 
You can easily resize duplicate PushButton objects. While you can’t see it, this Push- 
Button object has a caption of a single space. This makes it the only PushButton 



Figure 4.5 The beginning of the interface for the Keyboard program. This single PushButton object 
will be duplicated for all the keys on the keyboard except the Shift keys. 
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Figure 4.6 The original PushButton object has been duplicated to form the first row of keys. 



Figure 4.7 Rather than duplicating the next row one key at a time, you can highlight the row and 
duplicate it all at once. 
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Figure 4.8 The Keyboard program with all the keys added. 


object with a single-character caption that isn’t a letter. You’ll have to add special logic 
to handle this. Since the shifted and unshifted value of the spacebar are the same, you 
could have simply used two spaces as the caption and avoided the problem. 

Figure 4.9 shows the finished keyboard. The two Shift buttons are a single Push- 
Button object named PB_Shift that has been duplicated once. The Quit button is a 
third PushButton object, and the screen is a Descriptive Text object. In addition to 
having its background color changed to white, it has been formatted to use mono¬ 
spaced text so the screen will look more like a typewriter. 


REXX coding 

As impressive as the interface for Keyboard is, it uses almost no REXX coding. Add 
the following two lines to the Init section: 

Shift = "NO" 

TypedString = "" 


The first line configures the initial state to indicate the Shift key hasn’t been pressed, 
and the second initializes the variable that will be used to store the series of charac¬ 
ters “typed” by the user. The remaining REXX code is the GetKeyStroke subroutine 
that reads and processes the individual keystrokes, explained in Figure 4.10. Figure 
4.11 shows the final program in operation. 

































































Iexx Code 


IVX-R 


Explanation 


GetKeyStroke: 

Name of the subroutine. 

Letter = VRGet(VRInfo("Object"), "Caption") 

Use the VRGet function to 
obtain the caption of the Push 
Button key that was pressed. 

IF Length(Letter) = 1 THEN 

DO 

If the length was one, then it 
was either a letter or the space¬ 
bar, so do the following. 

IF Shift = "YES" THEN Typed = Letter 

If the last key pressed was the 
Shift key, then use the uppercase 
letter that was used as the cap¬ 
tion and store it to the variable 
Typed. 

ELSE Typed = Translate(Letter," abode 
fghijklmnopqrstuvwxyz", 

" ABCDEFGHIJKLMNOPQRSTUVWXYZ") 

Otherwise, the variable was a 
lowercase variable, so convert 
the uppercase cpation to lower¬ 
case using the Translate func¬ 
tion. Notice that a space is used 
before the capital and lowercase 
As and this takes care of the 
“translation” of the space char¬ 
acter automatically. 


Figure 4.10 The GetKeyStroke subroutine, which handles processing the keystrokes in the Keyboard 
program. 
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VX-Kexx Code 

Explanation 

END 

End of the DO loop. 

ELSE 

DO 

If the caption does not have a 
length of one, then do the fol¬ 
lowing since both the upper- and 
lowercase values are stored in 
the caption. 

Upper = SubStr(Letter,1,1) 

Store the first character ot the 
caption to the Upper variable. 

Lower = SubStr(Letter,2,1) 

Store the second character ot the 
caption to the Lower variable. 

IF Shift = "YES" THEN Typed = Upper 

If the last key pressed was the 
Shift key then use the contents 
of the Upper variable. 

Else Typed = Lower 

Otherwise, use the contents ot 
the Lower variable. 

END 

End of the DO loop. 

TypedString = TypedString || Typed 

Append this character onto the 
string containing all the charac¬ 
ters that have been typed. 

IF Length(TypedString) > 400 THEN TypedString^ 
SubStr(TypedString,50,Length(TypedString)-49) 

If the length of this string 
exceeds 400 then strip off the 
first fifty characters. This will 
simulate scrolling and prevent 
the characters to display from 
exceeding the available display 
space. 

CALL VRSet "DT_Screen", "Caption", TypedString 

Use the VRSet function to make 
the variable containing the typed 
characters the caption of the 
Descriptive Text object. 

Shift - "NO" 

Turn off the shift setting so 
pressing Shift impacts only the 
next character. 

return 

Exit the subroutine. 


Figure 4.10 Continued. 


Summary 

PushButton objects will be an important part of most of your programs and this 
chapter shows you how to use them. Music uses eight different PushButton objects 
to play eight different notes. Music-2 uses eight copies of the same PushButton ob¬ 
ject to play the same notes. Keyboard uses the same approach to simulate a key¬ 
board using only three different PushButton objects, one of which is the Quit button. 
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Figure 4.11 The Keyboard program in operation. 

















Chapter 

5 

Other Buttons 


In Chapter 4, you saw that PushButton objects are used to initiate action. When you 
need to ask the user a yes or no question and you don’t need the answer right away, 
then a RadioButton object or CheckBox object is a good approach. Use the Ra- 
dioButton object when you have several options and only one can be selected; use 
the CheckBox object when you have several options and any number of them can be 
selected. 


Survey 

Survey is a sample survey program that asks users their gender, age, and income us¬ 
ing RadioButton objects, and which of five major appliances they own using Check- 
Box objects. It performs error-checking to make sure that gender, age, and income 
are entered, displays the results of the last response on the screen, clears all the but¬ 
tons, and waits for the new user to take the survey. It displays an error message 
when the user fails to enter required information. Teachers writing self-graded tests 
could use a very similar approach. 


User interface 

In this sample survey, income has three possible categories: under $20,000, $20,000 
to $40,000, and over $40,000. These three RadioButton objects are created first, as 
shown in Figure 5.1. Unless they’re grouped together using the GroupBox object, the 
user can set only one RadioButton object. When the user sets a second RadioButton 
by clicking on it, the first one is unset. 

By grouping some of the RadioButton objects together using a GroupBox object, 
as shown in Figure 5.2, you cause them to operate independently of the remaining 
RadioButton objects in the program. Only one RadioButton object inside the Group- 
Box object can be selected, but it doesn’t affect any RadioButton objects outside of 
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j fflj VX-REXX — SURVEY (C:\dS2SyXftEXX\EXAMPLES\SURVEYVSURVEY.VRP ' ' j °,j Dj 

[projec t Tools Windows Run Options Help | 



Figure 5.1 Three RadioButton objects that allow users to check their income bracket. 
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Figure 5.2 The three RadioButton objects being grouped into a GroupBox object so their settings don’t 
affect other RadioButton objects in the program. 


its GroupBox object. By using multiple GroupBox objects in your program, you can 
have as many sets of RadioButton objects as you like, with each set operating inde¬ 
pendently of the other sets of RadioButton objects. 

Once you use a GroupBox object to group RadioButton objects together, those Ra¬ 
dioButton objects cannot be moved outside the GroupBox object. You can add more 
RadioButton objects inside the GroupBox object, but you cannot move them outside 
the box. You can, however, use the VX-REXX pop-up menu to cut an object inside a 
GroupBox and then paste it outside the box. 

Figure 5.3 shows three sets of RadioButton objects, each inside its own GroupBox 
object. Note how the title for the GroupBox object is printed as part of its border and 
makes a nice place to enter a phrase that ties the RadioButton objects together. 
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The next step is to add the CheckBox objects. CheckBox objects function some¬ 
what like RadioButton objects, except that as many of them can be turned on as nec¬ 
essary. So RadioButton objects are used for mutually exclusive questions like age, 
where you can’t fall into two categories, and CheckBox objects are used for inde¬ 
pendent yes-or-no questions. 

Figure 5.4 shows the final user interface. Two PushButton objects have been 
added, one for users to click on to indicate they’re finished with the survey and an¬ 
other to end the survey. There are three Descriptive Text objects. One is used to dis¬ 
play the survey results, a second is used as a title above this object, and a third is 
used to display an error message when users don’t answer the age, income, or gen¬ 
der questions. 
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Figure 5.3 Three sets of RadioButton objects for age, income, and gender. 
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Figure 5.4 CheckBox objects in place for users’ major appliances. 
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REXX coding 

None of the RadioButton objects or CheckBox objects have a Click event associated 
with them since the program doesn’t need to take action just because a user clicks 
on a button. Program action takes place when the user clicks on the Survey Done or 
Quit buttons. The logic of allowing only one RadioButton object to be set in each 
GroupBox object is handled automatically by VX-REXX and requires no program¬ 
ming. The only line that was added to the Init line was: 


Return = "Od"x 


to store the value of a Return to the variable Return. Note that Od is the hexadecimal 
representation for a Return. (Actually, the representation is OdOa, but due to the way 
VX-REXX operates the Descriptive Text object needs only “half’ the Return to start 
a new line. Using the entire Return causes the text to be double-spaced. This isn’t 
true for other VX-REXX objects.) This line is necessary because you can’t enter the 
ASCII Return into the code. You need the Return variable to control where the dis¬ 
play wraps in the text displayed in the Descriptive Text object. Without it, lines 
would wrap only at points between words even if a new line of data started earlier. 
The REXX code for the Survey Done PushButton object is as follows: 


CALL ResetErrorMessage 
Error = CheckForErrors() 

IF Error = 3 THEN CALL FigureOut 
IF Error = 3 THEN CALL ResetButtons 

The first line erases any displayed error message. The second calls the CheckForErrors 
subroutine as a function. The third line calls the FigureOut subroutine to record the 
status of all the buttons, but only if there was no error. The last line calls the ResetBut¬ 
tons subroutine to clear all the buttons, but again only if the last entry was error-free. 

The CheckForErrors function simply “adds” the value of each of the nine Ra¬ 
dioButton objects. They have a value of one if they’re set and zero otherwise. There 
are three GroupBoxes so the value can never exceed three, but a value of zero, one, 
or two indicates that one or more of the GroupBox objects doesn’t have a value set. 
When this happens, it calls the SignalError subroutine to flag the errors. This sub¬ 
routine checks the totals in each GroupBox object separately to see which one is 
missing a value and creates a custom error message. That code is: 


ErrorMessage = "" 

GenderCheck = VRGet("RB_8", "Set") + VRGet("RB_9", "Set") 

IF GenderCheck <> 1 THEN ErrorMessage = "Gender Not Specified!" ! ! Return 

IncomeCheck = VRGet("RB_1", "Set") + VRGet("RB_2", "Set") + 

VRGet("RB_3", "Set") 

IF IncomeCheck <> 1 THEN ErrorMessage = ErrorMessage ! ! 

"Income Not Specified!" !! Return 
AgeCheck = VRGet("RB_4", "Set") + VRGet("RB_5", "Set") 

AgeCheck = AgeCheck + VRGet("RB_6", "Set") + VRGet("RB_7", "Set") 

IF AgeCheck 1 THEN ErrorMessage = ErrorMessage ! ! "Age Not Specified!" 

CALL VRSet "DT_Error", "Visible", 1 

CALL VRSet "DT_Error", "Caption", ErrorMessage 

CALL Beep 500, 500 
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The code VRGet(“RB_8”, “Set”) returns a one if this RadioButton object has been set 
and a zero otherwise, so most of the code simply involves computing totals for the 
three GroupBox objects separately and adding an error message to the ErrorMes- 
sage variable if the total isn’t one. 

Note how the Return variable is appended on the end of the ErrorMessage vari¬ 
able at the end of each error message. This forces another line before a second mes¬ 
sage is added, without depending on the automatic word wrap. Using this approach, 
each error message is displayed on a separate line. 

Also note that, when a line of code is too long to be displayed on a single line, the 
line is continued, with the second line indented a single space. This is done through¬ 
out the book. 

The FigureOut subroutine handles the bulk of the processing for the RadioButton ob¬ 
jects and CheckBox objects. It’s explained in detail in Figure 5.5. Figure 5.6 shows the 
final program in operation. This screen shot shows the program after a user has clicked 
on Survey Done without answering all the questions, so an error message is generated. 


VX-Rexx Code 

Explanation 

FigureOut: 

Name ot the subroutine. 

Automobile = "No" 

Store an initial value to the 
Automobile variable. 

IF VRGet("CB_Automobile", "Set") = 1 

THEN Automobile = "Yes" 

It the user clicked on this 
CheckBox, then the VRGet 
function will return a one, so 
change the variable value to 

Yes. 

House = "No" 

Store an initial value to the 

House variable. 

IF VRGet("CB_House", "Set") = 1 

THEN House = "Yes" 

If the user clicked on this 
CheckBox, change the variable 
value to Yes. 

Stereo = "No" 

Store an initial value to the 

Stereo variable. 

IF VRGet ( "CB_Stereo","Set" ) = 1 THEN 

Stereo = "Yes" 

If the user clicked on this 
CheckBox, change the variable 
value to Yes. 

TV = "No" 


IF VRGet("CB_TV" / "Set") = 1 THEN TV = "Yes" 

If the user clicked on this 
CheckBox, change the variable 
value to Yes. 

Cycle = "No" 

Store an initial value to the 

Cycle variable. 

IF VRGet("CB_Cycle", "Set") = 1 THEN 

Cycle = "Yes" 

If the user clicked on this 
CheckBox, change the variable 
value to Yes. 

Income = "Under $20,000" 

Store an initial value to the 
Income variable. 


Figure 5.5 The VX-REXX code that handles processing the RadioButton and CheckBox objects. 
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Va-Rexx Code ' 

Explanation 

IF VRGet ( "RB_2 " , " 

Set" 

= i 

If the user clicked on this 

THEN Income = " 

$20,000 

RadioButton, change the vari- 

To $40,000" 



able value to reflect this. 

IF VRGet("RB_3", " 

Set" 

) = 1 THEN 

If the user clicked on this 

Income = "Over 

$40, 

000" 

RadioButton, change the vari¬ 
able value to reflect this. 

Age = "Under 18" 

Store an initial value to the Age 
variable. 

j IF VRGet ( "RB_5", " 

Set" 

) = 1 THEN 

If the user clicked on this 

Age = "18 To 35" 


RadioButton, change the vari- 




able value to reflect this. 

IF VRGet("RB_6", " 

Set" 

) = 1 THEN 

If the user clicked on this 

Age = "36 To 65" 


RadioButton, change the vari- 




able value to reflect this. 

IF VRGet ( "RB_7", n 

Set" 

) = 1 THEN 

if the user clicked on this 

Age = "Over 65" 



RadioButton, change the vari¬ 
able value to reflect this. 

Gender = "Male" 

Store an initial value to the 
Gender variable. 

IF VRGet ( "RB_9", " 

Set" 

) = 1 THEN 

If the user clicked on this 

Gender = "Female" 


RadioButton, change the vari- 




able value to reflect this. 

Results = 

"Gender.... 

Start constructing a variable 

..." || Gender 


Return 

containing the survey results. 

The II Return appends a Return 
onto the end of this line so the 
Descriptive Text object will start 
a new line. The contents of the 
Return variable were created in 
the Init section. 

Results = Results || 

"Age. 

Construct the remainder of the 

." II Age 


| Return 

report. 

Results = Results | 

"Income.. 


." Income 


|| Return 


Results = Results || 

"Automobile 


..." Automobile || 

Return 


Results = Results || 

"House... 


." | House 


Return 


Results = Results | 

"Stereo.. 


." Stereo 


|| Return 


Results = Results | 

"TV 



." II TV 


| Return 


Results = Results | 

"Motorcycle 


..." Cycle 

l 

Return 


CALL VRSet "DT_1", " 

Caption", 

Set the report variable to be the 

Results 



caption of the Descriptive Text 
object. 


Figure 5.5 Continued. 
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rGender- 
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1 35 Automobile 
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©Over $ 40,000 
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Figure 5.6 Running the Survey program. Note that an error message is currently visible on the screen. 
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Figure 5.7 Running the Music-3 program nicknamed “tiny piano.” This program uses 
RadioButton objects as keys. 


Music-3 

While programs don’t usually react immediately when you click on a RadioButton or 
CheckBox object, as you saw with Survey, VX-REXX can easily produce a program 
that performs some action when the user clicks on a RadioButton object or Check- 
Box object, as Music-3 shows. Music-3 is a version of Music-2 that plays the scales, 
except the keys have been replaced with RadioButton objects. 

In producing Music-3,1 reduced the work area to a tiny strip of screen just large 
enough for the eight RadioButton objects and a RadioButton object to quit the pro¬ 
gram. The Click event for each RadioButton object was a REXX command to beep 
the speaker, just as was used in the original Music program. The Click event for the 
quit RadioButton object was CALL Quit. The final program is shown in operation in 
Figure 5.7. 


Summary 

This chapter shows how to incorporate RadioButton objects and CheckBox objects 
into programs, as well as how to group them together. The Survey program uses both 
types of objects to get information from the user. Music-3 shows that VX-REXX pro¬ 
grams can react immediately to these objects by replacing the music keys in Music 
with RadioButton objects. 














Chapter 

6 


Getting Text Data from the User 


PushButton, RadioButton, and CheckBox objects are great ways to get small 
amounts of information from the user. However, they’re cumbersome if you want 
more information, such as the name of a file to edit. In this chapter, you’ll see how to 
get a lot of information from the user with an EntryField object and a MultiLine En- 
tryField object. 


Getting a Single Line with an EntryField Object 

You can use an EntryField object to obtain one long character string from the 
user. Of course, once you obtain that information, you can use REXX to split it 
into components. The EntryField object can also be seeded with a value for the 
user to edit. 


Lines 

The Lines program scrolls through an ASCII file, one line at a time. It displays the 
current line in an EntryField object. The filename is hardwired into the source code 
as LINES.TXT in the current subdirectory. If the user modifies the line, that new 
value is retained in memory. Once the end of the file is reached, the user can con¬ 
tinue to scroll forwards, adding new lines to the file. 

In addition to the EntryField object, it has four PushButton objects. They handle 
scrolling forwards, scrolling backwards, saving the data, and exiting the program. 
There’s also a hidden Descriptive Text object for displaying an error message if the 
user tries to scroll backwards at the beginning of the file. Figure 6.1 shows the pro¬ 
gram running. 

Interestingly, this program has no code associated with any of the events for the 
EntryField object. Since you can’t move from one line to another without clicking on 
either the forwards or backwards PushButton objects, I chose to handle the text 
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Figure 6.1 Running the Lines program. 


modifications with these buttons. The Click event for the backwards button calls the 
Backwards subroutine, which follows, with line numbers added for easy reference: 

1. /*:VRX */ 

2. Backwards: 

3. CALL Modified 

4. IF LineNumber > 1 THEN 

5. DO 

6. LineNumber = LineNumber - 1 

V. CALL VRSet "EF_1", "Value", Line.LineNumber 

8. END 

9. ELSE CALL ErrorMessage "At First Record" 

10. return 

Line 3 calls another subroutine called Modified that stores the modified text to 
the stem variable. Line 4 checks to make sure it isn’t listing the first line of the file. 
If it isn’t the first line, it can scroll backwards, so line 6 reduces the line counter 
by one and line 7 seeds that value into the EntryField object. If line 6 determines 
that the first line is being displayed, then line 9 calls an error subroutine to acti¬ 
vate the Display Text box and display an error message. The code for the Modified 
subroutine is: 

/*:VKX */ 

Modified: 

Line.LineNumber = VRGet("EF_1", "Value") 
return 


The single line in the subroutine reads the contents of the EntryField object and 
stores it to the stem variable. If the user made no change to its value, then the origi¬ 
nal value is maintained. This routine doesn’t check to see if the user deleted the en¬ 
tire line and then remove that line from the file. Rather, when the user deletes the 
entire line, a null value is saved to the variable. However, the saving subroutine does 
not write null lines to the file. 

The Click event for the forwards PushButton object first calls a subroutine to re¬ 
set any error message in case one is displayed. It then calls the Forwards subroutine, 
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which is as follows, with line numbers added for easy reference: 

1. / * :VRX */ 

2. Forwards: 

3. CALL Modified 

4. IF LineNumber < Line.O THEN 

5. DO 

6. LineNumber = LineNumber + 1 

7. CALL VRSet "EF_1", "Value", Line.LineNumber 

8 . END 

9 . ELSE 

10 . DO 

11. LineNumber = LineNumber + 1 

12. Line.O = Line.O + 1 

13. CALL VRSet "EF_1", "Value", "" 

14. END 

15. return 

As before, line 3 calls the Modified subroutine to store the current contents of the 
EntryField object to the stem variable. Line 4 checks to see if the end of the file has 
been reached. If not, lines 6 and 7 are executed; if so, lines 11-13 are executed. 
When the end of the file has not been reached, line 6 increments the line number 
counter by one and line 7 seeds the associated stem variable into the EntryField ob¬ 
ject. When the end of the file has been reached, line 11 increments the line number 
counter, line 12 increments the stem variable counter, and line 13 seeds the Entry- 
Field object with a null value. 

The SaveData subroutine is executed as the Click event for the save PushButton 
object after calling on a subroutine to reset any displayed error message. It is as fol¬ 
lows, with line numbers added for each reference: 

1. /*:VRX */ 

2. SaveData: 

3. CALL Modified 

4. Okay = VRDeleteFile(BakFile) 

5. Okay = VRRenameFile(File, BakFile) 

6. DO I = 1 TO Line.O 

7. IF Line.I <> "" THEN RC = LineOut(File, Line.I) 

8. END 

9. RC = LineOut(File) 

10. return 

Line 3 calls the Modified subroutine in case the current EntryField object value has 
been changed. Line 4 deletes the current backup file. The value for the BakFile and 
File variables is set in the Init subroutine. Note that a built-in VX-REXX file handling 
function is used rather than a RexxUtil function. These VX-REXX functions are dis¬ 
cussed in detail in Chapter 12. Line 5 renames the current data file to be the backup 
file, again using a built-in VX-REXX function. Lines 6-8 loop through all the lines of 
data, with line 7 writing any non-null variables to the data file. Line 9 closes the file. 
This is required or the next time the data is saved VX-REXX won’t be able to rename 
the file (because it’s in use), so the new data will be appended to the end of an ex¬ 
isting data file rather than being written to a new data file. 

The remaining sections of Lines duplicate techniques that have been discussed 
earlier in the chapter. 
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Todo-1 


Todo-1 is a “things to do” management program. It allows you to store descriptive 
lists of the things you want to accomplish along with an associated priority. You’ll be 
adding features and improving its interface as you learn new techniques. This ver¬ 
sion allows you to perform the following tasks: 

■ Scroll forwards 

■ Scroll backwards 

■ Save modified data 

■ Print the to-do list 

■ Edit existing to-do items 

■ Change the priority of existing to-do items 

■ Erase existing to-do items 

■ Mark existing to-do items as done 

This version can’t add new items to the to-do list, so it’s not yet a complete package. 
Its subdirectory, however, contains an existing to-do list, so you can experiment with 
the program. The interface is not yet finished, but there are advantages to discussing 
the basic framework of the program. 

If you have a VGA display, you’ll find that all of Todo-1 won’t fit on the screen in 
design mode. You can move the design area around so you can work on all parts of 
the program, and Todo-1 will fit on a VGA screen while running. Normally, you 
move the design area by dragging the title bar, but this might not let you reach the 
bottom of a large screen designed under a higher resolution. You can solve this by 
holding down the Ctrl key, clicking on the background with the right mouse but¬ 
ton, and holding down the right mouse button as you drag the design area. This 
will allow you to move the title bar up off the screen and access areas you couldn’t 
otherwise reach. 

For Writing OS/2 REXX Programming, I wrote a REXX to-do program called 
TODO.CMD that had most of the features we’ll add to the VX-REXX version, includ¬ 
ing full-screen editing of existing to-do items. TODO.CMD itself handles most of this, 
but it calls INTERACT.CMD as an external subroutine to handle the full-screen edit¬ 
ing. There is a copy of TODO.CMD and INTERACT.CMD in the \REXX subdirectory 
of the CD-ROM that comes with this book. 

User interface 

This will be the first example program in this book that approaches the complexity 
of a fully functional, realistic application. For that reason, it contains a significant 
portion of REXX code to complement the VX-REXX code. Before looking at it, how¬ 
ever, let’s review the VX-REXX interface for the program. 

Figure 6.2 shows the start of the program. This single line will be used to control 
one to-do item. The RadioButton objects on the left will control the priority. Next to 
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Figure 6.2 The initial EntryField and associated objects for the Todo program. 


those are two PushButton objects. One is used to indicate that an item has been fin¬ 
ished while the other simply erases the item, presumably because you no longer plan 
to accomplish that item. Both remove the item and its associated priority from the 
system. The only difference is that marking an item as done saves a copy of that item 
in the “done” file along with the date and time you flagged the item as done. On the 
right is an EntryField object that’s used to store the actual to-do item. This allows for 
easy editing, and all the items in this list can be edited even though new items can¬ 
not be added. 

Once the first line is finished, it’s copied eleven times so multiple to-do items 
can be displayed. Each row of objects is named individually rather than sharing a 
common name. That is, the low-priority RadioButton objects are named 
RB_Low_l through RB_Low_12. This makes it much easier to identify which but¬ 
ton is associated with a to-do item, a task the program has to accomplish many 
times. 

Once the twelve rows are added for the to-do items, the rest of the interface for 
this program is created. This includes a button to quit the program, save the data, 
scroll forwards, scroll backwards, and print the data. There’s also a Descriptive Text 
object for displaying a message when the data has been modified but not yet saved. 
This is shown in Figure 6.3. Finally, Figure 6.4 shows the program in operation. 
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Figure 6.3 The completed user interface for the Todo program. 
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Figure 6.4 Todo running with simulated data. 
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Overall organization 

The low, medium, and high RadioButton object Click events (3, 2, and 1) call the 
Low, Medium, and High subroutines respectively. Calling the same subroutine 
greatly reduces the number of subroutines required by the program. The done, 
erase, save, quit, forwards, backwards, and print PushButton object Click events call 
the Done, Erase, Save, Quit, Forwards, Backwards, and Print subroutines respec¬ 
tively. Finally, the EntryField object Change event calls the Changed subroutine. 

REXX and VX-REXX Code 

Twenty-one of the subroutines are discussed in the following sections: 


Backwards 

This simple subroutine scrolls the display backwards. If the display is already at the 
beginning of the file, then the backwards button is not visible. The code for this sub¬ 
routine is: 


StartShowingData = Max(StartShowingData - 11, 1) 
CALL SetTodoItems 

CALL ScrollButtons StartShowingData, Finish, Todo.0 


The first line computes the starting point for the next display. It will be either 11 
lines back (so one line overlaps with the last display) or the beginning of the file if 
there aren’t 11 lines to scroll back. The next line calls a subroutine to display the to- 
do items, and the third line calls a procedure to figure out which of the scrolling but¬ 
tons need to be displayed. Note that this procedure is passed three parameters. 


Changed 

This subroutine is activated by the Change event of each of the 12 EntryField ob¬ 
jects. It figures out which EntryField object was changed and then stores the modi¬ 
fied value to the corresponding stem variable. It also turns on the modified 
Descriptive Text object so the user will know the data has been modified. The oper¬ 
ation of this subroutine is explained in detail in Figure 6.5. 

CheckForDoneFile 

This subroutine checks to see if the “done” file already exists. If so, nothing is done. 
If not, it’s created. The code is as follows: 

/*:VRX */ 

CheckForDoneFile: 

ExistCheck = VRFileExists(DoneFile) 

IF ExistCheck = 1 THEN RETURN 
ELSE 
DO 

CALL LineOut DoneFile, "Date Done Time Done Priority Task" 

CALL LineOut DoneFile, "- - - -" 

END 


return 
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VX-kExx Code - 

Explanation 

Changed: 

Name of the subroutine. This 
subroutine is the Change event 
for the EntryFields. 

IF Modified = "NO" THEN CALL Modified 

If the data is not yet modified, 
then call a subroutine to mark it 
as modified. 

Name = VRGet(VRInfo("Object"), "Name") 

Use the VRGet VXRexx func¬ 
tion to find out the name of the 
EntryField that has been 
changed. 

DO 1=1 TO 12 

TestName = "EF_" || I 

IF Name = TestName THEN Changed = I 

END 

Loop through all twelve possible 
names looking for a match to 
find the number of the changed 
EntryField. 

Object = "EF_" Changed 

Store the name of the changed 
EntryField to a variable. 

TodoToChange = StartShowingData + Changed - 1 

Figure out the number of the 
changed to-do item by adding its 
row position to the starting point 
of the screen and subtracting 

one. 

Todo.TodoToChange = VRGet(Object , "Value") 

Use the VRGet VXRexx func¬ 
tion to get the changed contents 
of the EntryField and store that 
to the appropriate stem variable. 

return 

Exit the subroutine. 


Figure 6.5 The Changed subroutine of the Todo program. 


The first operational line uses a VX-REXX function to see if the done file exists. Its 
name is stored in the DoneFile variable. If it exists, the second line issues a Return 
command to exit the subroutine. If it doesn’t exist, the remaining lines create the file 
and store header information to that file. 


Done 

This subroutine figures out which to-do item is done, writes the information on the 
completed to-do item to the “done” file, and then erases that line from the to-do 
data. Its operation is shown in Figure 6.6. 


Erase 

This subroutine figures out which to-do item to erase and then erases that line from 
the to-do data. Its operation is identical to the Done subroutine, with the single ex¬ 
ception that it doesn’t write any information to the done file. For that reason, its 
code is not displayed. 
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Forwards 


This simple subroutine scrolls the display forwards. If the display is already at. the 
end of the display, then the forwards button is not visible. The code for this subrou¬ 
tine is: 


/*:vrx */ 

Forwards: 

StartShowingData = Min(StartShowingData + 11, Todo.0 -11) 
CALL SetTodoItems 

CALL ScrollButtons StartShowingData, Finish, Todo.0 
return 


VX-kEXX Code- 

Explanation 

Done : 

The name of the subroutine. 

This subroutine writes finished 
to-do items to the “done” file and 
then erases it from the to-do list. 

CALL CheckForDoneFile 

Call a subroutine that makes 
sure the done file already exists. 
It not, that subroutine creates it 
and adds the appropriate header 
to the file. 

DonePBNumber = VRGet (VRInfo ( "Object" ) , "Name" ) 

Use the VRGet VXRexx func¬ 
tion to get the name of the done 
button that was pushed. 

DO I = 1 TO 12 

TestName = "PB_Done_" || I 

IF DonePBNumber = TestName THEN Changed = I 

END 

Loop through all twelve possible 
names looking for a match to 
find the number of the done 

Push Button that was pushed. 

DoneNumber = StartShowingData + Changed - 1 

Store the name of the done Push 
Button to a variable. 

Done = Todo.DoneNumber 

DonePriority=Priority.DoneNumber 

Store the associated to-do item 
and priority to variables. 

ToSave = Date () [“["“^ " || TIME ( 'C' ) 

| " " DonePriority || " " 

| Done 

Store those variables to a com¬ 
posite variable along with the 
current date and time. 

CALL LineOut DoneFile,ToSave 

Write the composite variable out 
to the done file. 

CALL LineOut DoneFile 

Close the file. 

DROP Done DonePriority DonePBNumber 

Drop unneeded variables. 

CALL Killlt DoneNumber j 

Call a subroutine to delete this 
to-do item and associated priority 
now that it has been written to 
the done file. 

return 

Exit the subroutine. 


Figure 6.6 The Done subroutine of the Todo program. 
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VX-Rexx Code 

Explanation 

High : 

Name of the subroutine. This 
subroutine handles users click¬ 
ing on the RadioButton to 
change a priority to high. 

Similar subroutines handle the 
user clicking on a medium or 
low priority. 

Name = VRGet(VRInfo("Object " ), "Name") 

Get the name of the object that 
was clicked on. 

DO 1=1 TO 12 

TestName = "RB_High_" || I 

IF Name = TestName THEN Changed = I 

END 

Use the VRGet VXRexx func¬ 
tion to find out the name of the 
priority RadioButton that was 
changed. 

Modified = StartShowingData + Changed - 1 

Loop through all twelve possible 
names looking for a match to 
find the number of the changed 
RadioButton. 

Priority.Modified = 1 

Change the priority of the stem 
variable to the appropriate 
value. 

CALL Modified 

Call a subroutine to mark the 
data as being modified. 

return 

Exit the subroutine. 


Figure 6.7 The High subroutine of the Todo program. 


The first operational line figures out the starting point. If less than 11 lines remain to 
be scrolled, it starts at the point that allows the last line to be displayed at the bot¬ 
tom. Otherwise, it scrolls forwards 11 lines so there will be one line of overlap. The 
second line calls a subroutine to display the to-do items, and the third line calls a 
subroutine to figure out which scrolling buttons to display. 


High 

This subroutine is activated when the user clicks on the high RadioButton object to 
change the priority of a to-do item to high. It figures out which to-do item is being 
changed and changes the appropriate stem variable. Its code is explained in Figure 6.7. 


This is the usual VX-REXX initialization subroutine, and not all of its code is dis¬ 
played. However, it has been modified to create several variables that are used later 
in the program, and that portion of the code is shown. It also calls two subroutines, 
one to read in the data and a second to set up the initial display. Since this is fairly 
simple code, I won’t explain it line by line. 


InFile 

BakFile 

DoneFile 


"TODO.DO" 

"TODO.BAR“ 
"TODO.DUN" 
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Printer = "LPT1" 
StartShowingData = 1 
CALL Read_Data 
CALL SetTodoItems 
Modified - "NO" 


Kill!! 

This subroutine performs the actual deletion of to-do items for either the Done or 
Erase subroutines. Rather than actually deleting a to-do item, however, it moves all 
the items above it down one and decreases the counter by one so the last item is ig¬ 
nored. Take care when there’s only one to-do item remaining or when the last item 
is being erased. The code for this subroutine is explained in detail in Figure 6.8. 


Low 

This subroutine is activated when the user clicks on the low RaclioButton object to 
change the priority of a to-do item to low. It figures out which to-do item is being 



Explanation 

Killlt: 

Name of the subroutine. This 
subroutine is called by the Done 
and Erase subroutines to remove 
the to-do item and priority. 

ToKill = Arg(l) 

Obtain the number of the to-do 
item to delete from an argument 
passed to the subroutine. 

IF Todo.0 = 1 THEN 

DO 

If there is only one to-do item, 
then that is the one to erase, so 
do the following. 

DROP Todo.1 

Drop the variable from memory. 

o 

ii 

o 

o 

ir d 

o 

:eh 

Reset the to-do counter variable 

to zero. 

CALL SetTodoItems 

Call a subroutine to hide the 
unneeded objects on the screen. 

CALL Modified 

Call a subroutine to flag the data 
as being modified. 

RETURN 

Exit the subroutine. 

END 

End of‘ the IF Todo.O = 1 loop. 

IF ToKill - Todo.0 THEN 

DO 

if the last to-do item is to be 
dropped, then perform the fol¬ 
lowing. 

DROP Todo.ToKill 

Drop the variable. 

Todo.0 = Todo.0-1 

Decrease the counter by one. 

CALL SetTodoItems 

Call a subroutine to hide the 
unneeded objects on the screen. 

CALL Modified 

Call a subroutine to flag the data 
as being modified. 

RETURN 

Exit the subroutine. 


Figure 6.8 The Killlt subroutine of the Todo program. 
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VX-Rexx Code 

Explanation 

END 

End of the IF ToKill = Todo.O 

DO I = ToKill To Todo.O - 1 

If the subroutine reaches this 
point, then the to-do item to 
delete is not the only one and 
not the last one, so loop through 
all the to-do items above this 
item. 

Old =1+1 

Priority.I = Priority.Old 

Todo.I = Todo.Old 

Store the priority and to-do text 
for the item above this slot to 
this slot. This moves all the 
items above the item to be delet¬ 
ed down one slot, overwriting 
the item to erase in the process. 

END 

End of the t)0 1 = ToKill To 
Todo.O - 1 loop. 

Todo.0 = Todo.0-1 

Reduce the counter by one. 

CALL SetTodoItems 

Call a subroutine to hide the 
unneeded objects on the screen. 

CALL Modified 

Call a subroutine to flag the data 
as being modified. 

return 

Exit the subroutine. 


Figure 6.8 Continued, 


changed and changes the appropriate stem variable. It’s very similar to the High sub¬ 
routine, so its code isn’t shown. 


Medium 

This subroutine is activated when the user clicks on the medium RadioButton object 
to change the priority of a to-do item to medium. It figures out which to-do item is 
being changed and changes the appropriate stem variable. It is very similar to the 
High subroutine. 

Modified 

This subroutine is called any time data is modified. Its code is as follows: 

/*:VRX */ 

Modified: 

Modified = "YES" 

Okay = VRSet("DT_Modified", "Visible", 1) 
return 


The first operational line changes a variable flag to indicate the data has been modi¬ 
fied, and the second line displays the modified Descriptive Text object. 
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Print 


This subroutine loops through all the to-do items and prints them to the printer. Its 
code is: 

/*:VRX */ 

Print: 

CALL LineOut Printer, "Priority Task" 

DO 1=1 TO Todo.0 

LineToPrint = Priority.I " " Todo.I 

CALL LineOut Printer, LineToPrint 

END 

CALL CharOut Printer, 'OC'x 
return 


The first operational line prints a header to the printer. (The Printer variable stores 
the value of LPT1 to indicate a printer.) The next four lines loop through all the to¬ 
do items and associated priorities, and print them. The final line sends a form feed 
character to the printer to eject the page. 


Read_Data 


This subroutine is called only once, when the program first starts. It initially reads 
the data from the data file into stem variables. Its code is as follows: 

/*:VRX */ 

Read_Data: 

Count = 0 

DO WHILE LINES(InFile) 

Count = Count + 1 

Priority.Count = Lineln(InFile) 

Todo.Count = Lineln(InFile) 

END 

Todo.0 = Count 
CALL LineOut InFile 

IF Todo.O < 12 THEN CALL WindowControl 
return 


The first operational line creates a counter variable. The next five lines loop through 
the file until all the lines are exhausted, reading a priority off one line and the to-do item 
off the next. The seventh line stores the count to the Todo.O stem variable, the eighth 
closes the file, and the last line calls a subroutine if there are less than 12 to-do items so 
the unnecessary EntryField objects and their associated buttons can be hidden. 


Save 


This subroutine saves the data to a file. First it deletes the existing backup file, and 
then it renames the existing data file to be the new backup file. In this manner at 
least one copy of the data is always on the disk. Both of these steps are performed 
using VX-REXX functions. After this, it writes the data to a newly created data file. 
Its operation is explained in detail in Figure 6.9. 
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VX-Rexx Code 

Explanation 

Save : 

Name of the subroutine. This 
subroutine saves the data to 

disk. 

CALL VRDeleteFile BakFile 

Call the VRDelete VX-REXX 
function to delete the current 
backup file. 

CALL VRCopyFile InFile, BakFile : 

Call the VRCopyEile VX-REXX 
function to copy the current data 
file to the backup file. 

CALL VRDeleteFile InFile 

Use the VRDeleteFile VX-REXX 
function to delete the current 
data file. By copying before 
deleting, a copy of the data file 
always exists on the disk in case 
there is a problem. 

CALL Sort 

Call a subroutine to sort the 

data. 

CALL SetTodoItems 

Since the data has been sorted, 
its order might have changed, 
so call a subroutine to redisplay 
the data. 

DO 1=1 TO Todo.O 

CALL LineOut InFile,Priority.I 

CALL LineOut InFile, Todo.I 

END 

Loop through all the data and 
write it to a disk file. For ease of 
coding, the priority and to-do 
item are written to different 

lines. 

CALL LineOut InFile 

Close the file. 

CALL UnModified 

Call a subroutine to turn off the 
modified Descriptive Text box 
since the data in memory now 
matches the data on disk. 

return 

Exit the subroutine. 


Figure 6.9 The Save subroutine of the Toclo program. 


ScrollButtons 

This procedure controls the display of scrolling buttons. Its code is: 


/*:VRX */ 

ScrollButtons: 

PROCEDURE 

ScreenStart = Arg(1) 

ScreenFinish = Arg(2) 

TodoCount = Arg(3) 

IF ScreenFinish < TodoCount THEN Okay = VRSet("PB_Forwards", 
"Visible", 1) 

ELSE Okay = VRSet("PB_Forwards", "Visible", 0) 

IF ScreenStart > 1 THEN Okay = VRSet("PB_Backwards", "Visible", 1) 
ELSE Okay = VRSet("PB_Backwards", "Visible", 0) 
return 











Getting Text Data from the User 73 


The first operational line hides all the variables. The next three lines read in the 
starting and ending lines of the screen and the total number of to-do items from ar¬ 
guments passed to the subroutine. The next two lines display the forwards Push- 
Button object if the ending point of the screen is less than the number of to-do items, 
and hides it if the last screen item matches the number of to-do item. The last two 
lines display the backwards PushButton object if the first screen line is more than 
one, and hides it otherwise. By hiding these buttons when their use is inappropriate, 
the Forwards and Backwards subroutines don’t need to check and see if scrolling is 
appropriate and display an error message when they cannot scroll as requested. 

SetTodoltems 

This subroutine actually displays the to-do items and their associated priorities. It’s 
called initially, after scrolling in either direction and after saving the data. It’s called 
after saving the data because the data is sorted before saving. 

SetTodoltems uses VRSet to place the to-do items into the EntryField objects. How¬ 
ever, this causes the EntryField object Change event to be activated. So the program 
turns on the modified flag. However, you don’t want the modified flag turned on simply 
because an initial value was placed into the field, so the subroutine turns off the Change 
event code, inserts the initial value, and then it reinitializes the Change event code. The 
operation of this very interesting subroutine is explained in detail in Figure 6.10. 


VX-kExx Code 

Explanation 

SetTodoltems: 

Name of the subroutine. This 
subroutine stores the to-do items 
into the EntryFields and the pri¬ 
orities into the RadioButtons. 

/* Save Existing Change Event Instructions 
And Then Clear Change Event Instruction 
Temporarily For Loading Initial Values */ 

Comments. 

DO I = 1 TO 12 

EF = "EF_" | | I 

Store.I = VRGet(EF, "Change") 

Okay=VRSet(EF, "Change", "") 

END 

Loop through all twelve 
EntryFields and save the current 
contents of their Change event 
to a variable using the VRGet 
VX-REXX function. After that, 
reset the Change event to null 
using the VRSet VX-REXX | 

function. This is required 
because using VRGet to store an 
initial value to an EntryField 
triggers its Change event, which 
needs to be avoided in this case 
since, in this program, that 
marks the data as modified and 
no modifications have taken 
place so far. 


Figure 6.10 The SetTodoltems subroutine of the Todo program. 
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maiui 1 rii wmmmmmmmmmmmmm 

Explanation 

/* Now, Load Initial Values */ 

Comment. 

CALL WindowControl 

Call a subroutine to hide any 
unneeded rows of objects. 

Line = 0 

Create a variable to count the 

row numbers. 

Finish = MIN(Todo.O, StartShowingData + 11) 

Compute the finishing point for 
the display. 

Start = StartShowingData 

Store the starting point to a vari¬ 
able. 

DO I = Start TO Finish 

Loop through from the starting 
to ending point of the display. 

Line = Line + 1 

Increase the row counter vari¬ 
able. 

Object = "EF_" Line 

Create a variable with the name 
of the EntryField to control on 
this loop. 

Okay = VRSet(Object, "Value", Todo.I) 

Store the to-do text to this 
EntryField. 

Low = "RB_Low_" | Line 

Medium = "RB_Medium_" | | Line 

High = "RB_High_" || Line 

Create a variable with the name 
of the priority RadioButtons to 
control on this loop. 

IF Priority.I = 3 THEN 

Okay=VRSet(Low,"Set", 1) 

IF Priority.I = 2 THEN 

Okay=VRSet(Medium,"Set " , 1) 

IF Priority.I = 1 THEN 

Okay=VRSet(High,"Set " , 1) 

Store the associated priority to 
the proper RadioButton. 

END 

End of the DO I = Start TO 
Finish loop. 

/* Restore Original Commands */ 

Comment. 

DO 1=1 TO 12 

EF = "EF_" || I 

Okay=VRSet(EF,"Change",Store.I) 

END 

Loop through and restore the 
original Change events to the 
EntryFields. 

DROP Store. 

Drop this unneeded stem vari¬ 
able. 

CALL ScrollButtons StartShowingData, 

Finish, Todo.0 

Call a subroutine to decide 
which scrolling buttons to dis- 
play. 

return 

Exit the subroutine. 


Figure 6.10 Continued. 


Sort 

This subroutine sorts the data first into priority order and then into alphabetical or¬ 
der among priorities. Its code is as follows: 


/*:VRX */ 
Sort: 
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DO J = 1 TO Todo.O - 1 
DO K = J+l to Count 

First = Priority.J !! Todo.J 
Second = Priority.K !! Todo.K 
IF First > Second THEN CALL Swap 

END 

END 

return 


The first operational line loops from the beginning of the list until the next-to-last 
item in the list. The second line begins at the current position of the first loop and 
loops until the end of the file (which is why the first loop skips the last item—so the 
second loop will have something to go to). The next two lines create composite vari¬ 
ables of two adjoining lines with their priority first, so sorting is first in priority order. 
The fifth line calls a subroutine to swap these two to-do items and associated priori¬ 
ties if they’re out of sequence. By the time the two loops are finished, the data is in 
the desired order. 


Swap 


This subroutine is called by the Sort subroutine to swap two to-do items when they’re 
out of sequence. This is fairly simple REXX code, so it’s presented without explanation. 

/*:VRX */ 

Swap: 

Temp = Todo.K 
Todo.K = Todo.J 
Todo.J = Temp 
Temp = Priority.K 
Priority.K = Priority.J 
Priority.J = Temp 
DROP Temp 
return 


UnModified 

This subroutine is called by the Save subroutine to clear the modified Descriptive 
Text object once data has been saved, so the version in memory matches the version 
in the data file. Its code is: 

/*:VRX */ 

UnModified: 

Modified = "NO" 

Okay = VRSet("DT_Modified", "Visible", 0) 
return 


The first operational line resets the variable flag and the second hides the Descrip¬ 
tive Text object. 


WindowControl 

This subroutine is called when there are less than 12 to-do items. It hides all the ob¬ 
jects that aren’t needed to display to-do items. Its operation is explained in detail in 
Figure 6.11. 
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VX-Rexx Code J 

Explanation 

WindowControl : i 

Name of the subroutine, d his 
subroutine controls which rows 
jf objects are visible and which 
ire not. 

u 

o 

H 

II 

•G 

o 

DO 

Loop through all twelve rows. 

Flag = 1 1 

Create a flag that defaults to one 
to indicate visible. 

IF Todo.O < I THEN Flag = 0 

If the row number exceeds the 
number of two items, then 
change the flag to a value that 
indicates invisible. 

LB = "EF_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(LB,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

PI = "PB_Erase_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(Pi,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

P2 = "PB_Done_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(P2,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

Rl = "RB_High_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(Rl,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

R2 = "RB_Medium_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(R2,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

R3 = "RB_Low_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(R3,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

GB = "GB_" j | I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(GB,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 


Figure 6.11 The WindowControl subroutine of the Toclo program. 
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Va-Kexx Code 

Explanation 1 2 

GB = "GB_" || I 

Create a variable storing the 
name of the object to control. 

Okay=VRSet(GB,"Visible",Flag) 

Set this object to visible or 
invisible depending on the value 
of the Flag variable. 

END 

End of the DO I = 1 TO 12- 

loop. 

return 

Exit the subroutine. 


Figure 6.11 Continued. 


As you can see, Todo-1 is a fairly complex program. However, I think it’s good to 
see a few realistically sized examples mixed in with the simpler examples. As you 
gain additional skills in this book, you’ll revisit and refine this program. 

Getting Multiple Lines with a MuitiLine EntryField Object 

You can use the MuitiLine EntryField object to obtain one long character string from 
the user. Unlike the EntryField object, the MuitiLine EntryField object allows the 
user to enter multiple lines of information. You can also seed the MuitiLine Entry- 
Field object with a value for the user to edit. The best way to illustrate a MuitiLine 
EntryField object is with an example, as follows: 


Lotiines 


The Lines program, shown previously, lets the user scroll through a sample ASCII file 
one line at a time and make changes to each line. The user can add additional lines 
to the end of the file. Lotlines performs the same task with a MuitiLine EntryField 
object. When the entire file fits on one screen, no scrolling is required. When the file 
is too long to fit on one screen, scrolling is handled by the mouse elevator that’s au¬ 
tomatically added by the MuitiLine EntryField object, so the programmer doesn’t 
have to worry about scrolling. For this reason, you would want to use a MuitiLine En¬ 
tryField object for displaying a lot of text. 

Figure 6.12 shows the user interface for Lotlines. The Init section creates the vari¬ 
ables containing the name of the data file and backup file. For the sample program, 
these are hardwired into the code. It then calls the GetData subroutine to load the 
data into memory. Finally, it loads the data retrieved by the GetData subroutine into 
the MuitiLine EntryField object. The code from the Init section that does this is: 

File = "LINES.TXT" 

BakFile = "LINES.BAK" 

CALL GetData 

CALL VRSet "MLE_1", "Value", EditLine 

The data is loaded into memory by the GetData subroutine. That subroutine is as fol¬ 
lows, with line numbers added for easy reference: 

1. GetData: 

2. Return = "0d0a"x 
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VX-REXX - LOTLINES (C:\0S2\VXREXX\EXAMPLESMPTLIHES\L0TLIN 
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Figure 6.12 The interface for Lotlines. 


3. DO WHILE LINES(File) 

4. Count = Count + 1 

5. Line.Count = Lineln(File) 

6. END 

7. Okay = LineOut(File) 

8. Line.O = Count 

9. IF Line.O = 0 THEN 

10. DO 

11. EditLine = "No Data Found!" 

12. RETURN 

13. END 

14. EditLine = "" 

15. DO 1=1 TO Line.O 

16. EditLine = EditLine !! Line.I I! Return 

17. END 

18. return 

Line 2 creates a variable containing a return. Lines 3-6 loop through the file storing 
each line to a stem variable. In the process, REXX strips off the Return at the end of 
each line, so you must add it back in. Line 7 closes the file. Line 8 stores the count to 
a stem variable. If the file were missing or empty, lines 9—13 would return a default 
value. When the file is found and is not empty, lines 14-17 loop through all the lines 
that were read and store them to a single variable, with a Return at the end of each 
line. It’s this variable that Init stores to the MultiLine EntryField object. 

The button to save the data calls the SaveData subroutine. This subroutine is as 
follows: 


SaveData: 

Okay = VRDeleteFile(BakFile) 
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Okay = VRRenameFile(File, BakFile) 
EditLine = VRGet("MLE_1", "Value") 
Okay = LineOut(File, EditLine) 

Okay = LineOut(File) 
return 


The subroutine deletes the existing backup file, renames the current data file to be 
the backup file, reads the data from the Multiline EntryField object, writes that data 
out to the now blank data file, and then closes the data file. 


Survey-2 

Recall from Chapter 5 that Survey is a sample survey program that asks users their 
gender, age, and income using RadioButton objects, and which of five major appli¬ 
ances they own using CheckBox objects. It performs error-checking to make sure 
gender, age, and income are entered, displays the results of the last response on the 
screen, clears all the buttons, and waits for a new user to take the survey. It displays 
an error message when the user fails to enter required information. Teachers writing 
self-grading tests could use a very similar approach. 

You’re going to modify Survey so that it uses a MultiLine EntryField object to 
query the user’s name and address. You’ll also modify the Descriptive Text object to 
display this additional information. The modified program is called Survey-2. 

Figure 6.13 shows the modified user interface for Survey-2. The only modifica¬ 
tions to Survey is a larger Descriptive Text object and the addition of a Mult iLin e 
EntryField object. However, reading the text from the MultiLine EntryField ob¬ 
ject and preparing it for display in the Descriptive Text object requires some ad¬ 
ditional work. 


VX-REXX — SURVEY-2 (C:\OS2WXREXX\EXAMPLES\MULTI\SURVEY-2. 
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Figure 6.13 The Survey-2 interface with the MultiLine EntryField object added to collect the user’s name 
and address. 
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Pressing Return at the end of a line automatically inserts two characters: a new- 
line character to move the text down one line and a linefeed character to move the 
text to the left of the new line. The Descriptive Text object deals with this 
newline/linefeed combination in a nonstandard way. Each is treated as a newline sig¬ 
nal with the text automatically moved to the left. That is why the FigureOut subrou¬ 
tine in Survey appended only a ‘Od’x character onto the end of each line rather than 
the ‘OdOa’x character most lines end with. 

If you simply read the text the user enters into the MultiLine EntryField object us¬ 
ing the VRGet function and display the Descriptive Text object using the VRSet func¬ 
tion, the text will end up double-spaced. To avoid this problem, the text coming from 
the MultiLine EntryField object must be parsed and the extra linefeed character re¬ 
moved. The user-defined function that Survey-2 uses to do this is: 


FigureOutName: 

PROCEDURE 
String = "" 

Value = VRGet("MLE_Name", "Value") 

DO FOREVER 

PARSE VAR Value Line 'OdOa'x Value 
IF String = "" Then String = Line 
ELSE String = String !! 'Oa'x !! Line 
IF Value = "" THEN LEAVE 

END 

return String 


Once the extra linefeed character has been removed, the name and address can be 
displayed in the Descriptive Text object in the normal fashion. If it were important 
for the program to separate the name and address components in order to put them 
into a database program, that task could also be accomplished in this subroutine. 

Figure 6.14 shows the program running. One entry has been completed and the 
program is waiting for another entry. 


Edit 


As Survey-2 shows, you can use a MultiLine EntryField object to enter a large 
amount of data. Of course, you can also use it to edit a large amount of existing data. 
The Edit program illustrates this. Edit functions as a very simple editor. You enter 
the name of a file to edit on the command line. If it exists, Edit will load it into a Mul¬ 
tiLine EntryField object for editing. If it doesn’t exist, you’ll be presented with a 
blank MultiLine EntryField object for data entry. Clicking on the save button erases 
the original version of the file and then writes the contents of the MultiLine Entry- 
Field object to that data file. No backup file is created. 

User interface 

Edit is a very simple program. You enter the name of the file to edit on the command 
line after the program name. If it already exists, it will be loaded into the MultiLine 
EntryField object for editing; otherwise, the MultiLine EntryField object will be left 
empty and ready to accept data. The code that does this follows, with line numbers 
added for easier reference: 



Getting Text Data from the User 81 


Survey-2 by Ronny Richardson 
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Figure 6.14 Survey-2 in operation. It’s waiting on a second response after one response was entered. 


1. LoadFile: 

2. FileToEdit = InitArgs.l 

3. WTitle = "Edit A File by Ronny Richardson " FileToEdit 

4. Okay = VRSet(Windowl, Caption, WTitle) 

5. Text = "" 

6. DO FOREVER 

7. IF Lines(FileToEdit) = 0 THEN LEAVE 

8. IF Text = "" THEN Text = Lineln(FileToEdit) 

9. ELSE Text = Text !! Return !! Lineln (FileToEdit) 

10. END 

11. Okay = LineOut(FileToEdit) 

12. Okay = VRSet(MLE_Edit, Value, Text) 

13. return 

Line 2 obtains the name of the file from the command line. Line 3 creates a title vari¬ 
able containing the program name and the name of the file to edit. Line 4 makes this 
variable the title of the main window. Line 5 resets the variable that will store the 
text. Lines 6-10 loop through the text file, reading all the text in that file. Line 11 
closes the file and line 12 sets the text into the MultiLine EntryField object. If the 
data file doesn’t exist, then the Text variable will be blank and a blank value will be 
set into the MultiLine EntryField object. 

At this point, the user interface for Edit is very simple. You can’t change to edit a 
new file without exiting the program, you can’t change the name of the file you’re edit¬ 
ing, and you can’t print. Your only two options are to quit the program and save the 
data back to the original file. And when you quit the program, it doesn’t check to see 
if the data has been saved first; it simply calls the Quit subroutine. You can save the 
data back to the data file, however, as many times as you like. The code to do that is: 


SaveData: 

Okay = VRDeleteFile(FileToEdit) 
Output = VRGet(MLE_Edit, Value) 
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Okay = LineOut(FileToEdit, Output) 
Okay = LineOut(FileToEdit) 
return 


This subroutine first deletes the original data file. Since no backup is created, if 
there’s a problem at this point all the data would be lost. This is okay in this example 
program, but would be inappropriate for production software. Then the contents of 
the MultiLine EntryField object are obtained and stored in the Output variable. 
Next, the Output variable is written out to the data file, and finally the data file is 
closed. The data is finally safe again. 

You might be surprised to learn that this code saves the entire contents of the Mul¬ 
tiLine EntryField object using the single REXX command Okay = LineOut (File 
ToEdit, Output) . Before I discuss that, however, let’s look at the format of the 
data file. 


Data format 

Figure 6.15 shows Edit running. Note that the data file has nine short lines, a blank 
line, a long paragraph, a blank line, and then the beginning of another long para¬ 
graph. You can see from the mouse elevator on the right that this is only the top of 
the data file. The portion you can see is followed by several more long paragraphs 
separated by blank lines. 

I created the first nine lines by typing each line and pressing Return at the end of 
each line. I created the blank lines by pressing Return twice at the end of a line. The 
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Figure 6.15 Using the Edit program to edit an existing data file. 
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Figure 6.16 When Edit stores its data to a file, it doesn’t insert a Return where the 
data word-wraps on the screen. 


long paragraphs don’t have a Return at the end of them; rather, the Multiline Entry- 
Field object automatically starts a new line every time the display tries to exceed the 
right margin. This is called wordwrap. The Multiline EntryField object does this 
without inserting extra characters into the data file. That way, as the data is edited 
the positions at which words wrap can change. Figure 6.16 shows the same data file 
in a program that doesn’t automatically use wordwrap, so each of the long para¬ 
graphs extends off to the right without a Return. 

So this particular data file has 14 lines of text. Some of these lines of text are sep¬ 
arated by blank lines (five in all), so the data file has 19 lines. Each of these 19 lines 
terminates with a ‘ODOA’x-linefeed-newline combination. 

To get back to the original issue, the reason you might be surprised to learn that 
this code saves the entire contents of the MultiLine EntryField object using the single 
REXX command previously discussed is that most people think of the REXX LineOut 
function as writing a single line of data to a file. However, what the LineOut function 
actually does is write the contents of a single variable to a file, only with a linefeed- 
newline combination appended to the end of the data. We tend to think of this vari¬ 
able as having only a single line because it rarely makes sense to create multiline 
variables in REXX. However, if a multiline variable is created in REXX, then the Line¬ 
Out function writes the entire contents of the variable to a data file with one line. 

The LINEOUT.CMD REXX program that comes with this book illustrates this. Its 
operational code is as follows: 


Variable = "Now is the time for all good men to come to the aid of their 
country. " 

Return = 'OaOd'x 

Text = Variable ! ! Variable ! ! Variable ! ! Variable ! ! Variable 1 ! Variable 

Text = Text ! ! Text ! ! Text ! ! Text 

Text = Text !! Return !! Return !! Variable 

Text = Text !! Return !! Return !! Variable 
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The full program has internal documentation, checks to see if the user requested 
command-line help by entering a /? on the command line after the program name, 
and checks to make sure the file specified in the FileName variable doesn’t al¬ 
ready exist. Also note that the Return variable contains the ‘ODOA’x linefeed-new¬ 
line combination. 


Summary 

You can obtain a single line of text from the user or allow the user to edit an existing 
single line of text using the EntryField object. You can obtain multiple lines of text 
from the user or allow the user to edit an existing text file using the MultiLine En¬ 
tryField object. 

Lines uses a single EntryField object to scroll through the LINES.TXT ASCII file— 
adding, deleting, and modifying its text, one line at a time. Todo-1 is the beginning of 
a to-do program. Lotlines uses a single MultiLine EntryField object to display and 
edit LINES.TXT. Survey-2 modifies Survey to accept the user’s name and address us¬ 
ing a MultiLine EntryField object. Edit uses a MultiLine EntryField object to edit any 
ASCII file. 









Chapter 


7 

Getting Specific 
Information from the User 


The EntryField object and MultiLine EntryField objects discussed in Chapter 6 are 
designed for unstructured data. That is, once the user begins entering data they’ll 
accept anything the user wants to type. Sometimes, however, you need the user to 
enter a particular type of data, such as a filename, or you want to have the user se¬ 
lect from a limited number of options. VX-REXX offers several functions to handle 
these needs. 

Picking a Filename with the VRFileDialog Function 

The VRFileDialog function offers a convenient way for the user to pick a filename 
when one is required. The function displays a standard OS/2 dialog box to use in se¬ 
lecting a file. Once the user has selected a file, its fully qualified name is returned by 
the function. The syntax is: 


FileName = VRFileDialog( object, title, type, [initialpath], 
[initial type], ["Drives. x "] , ["Types.x"] 


where: 

m Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists; if a null string is specified, the 
entire OS/2 desktop will be disabled. 

■ Title is the title of the dialog box. 

■ Type is the type of dialog box to use. The two types are 0 for open a file and S for 
save. 
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■ Initialpath is the initial path to use for displaying files. A file mask can be speci¬ 
fied to control the filenames that show in the dialog box. 

08 Initialtype is the initial type of file to show in the dialog box. The default is to 
show all files. 

■ Drives.^ is a stem variable that controls the drives displayed in the dialog box. 
Drives.0 must contain the number of drives, with Drive.l containing the first 
drive, Drive.2 the second, and so on. 

■ Types .x is a stem variable that controls the types of files displayed in the drop¬ 
down list. Types.0 must contain the number of file types, Types. 1 the first type, 
Types.2 the second type, and so on. 

The dialog box for the VRFileDialog function pops up over the original window for 
the program that’s currently running. Thus, the VRFileDialog function offers the first 
way to create multiwindow programs. VX-REXX has other dialog boxes that behave 
in the same fashion, and you’ll see how to use these later in this chapter. VX-REXX 
also offers other ways to use multiple windows in a single program. These will be ex¬ 
plored in Chapter 14. 


PickFile 


PickFile is a simple demonstration program that displays a dialog box for selecting a 
file when the user clicks on the top button. This choice is displayed in a Descriptive 
Text object, and the user can make another selection by clicking on the button again. 
Clicking on the bottom button terminates the program. 

PickFile is a simple program that shows the VRFileDialog function in action. Click¬ 
ing on the top button displays a dialog box where the user can select a file. This is 
shown in Figure 7.1. After the user makes a selection, its name is displayed in the 
Descriptive Text object. Clicking on the bottom button terminates the program. The 
Click event for the top PushButton object is: 

/*:VRX */ 

PB_l_Click: 

FileName = VRFileDialog, "Pick Any Of The Following Files", "0", "C: V") 

Files = Files !! FileName !! Return 
Okay = VRSet("DT_1","Caption", Files) 
return 


As you can see, the VRFileDialog function is a very handy tool for selecting files. 

This program is missing important error checking. While this is acceptable in a 
demonstration program, you need to be aware of the problem so you can avoid it in 
production software. The third line of the subroutine calls the VRFileDialog function 
to get the name of a file from the user. If the user selects a file, it works fine, but if the 
user clicks on the Cancel button, the VRFileDialog function returns a nul string, which 
is stored to the FileName variable. In this example, that will simply display a blank line 
on the screen. If the program depended on getting a valid filename, this would cause 
the program to crash. The point is that if your program depends on getting a valid file¬ 
name from the user, you must test the name supplied to make sure it’s valid. 
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C:\CONFIG.SYS 

F:\OS2\MDOS\WINOS2\ACCESSOR.GRP 

G:\0S2\B0S2REXX.EXE 


Open filename: 


Drive: _ 

[t: [gateway; 


Type of file: 
|<AU Fites> 


Directory: 


File: 

IAUTOEXECTBAT 
ICOMMAND.COM 
| CONFIG.SYS 

Idmdrvr.bin 

DSVXD.386 


a 123 
Q123R3 
Q123WIN 
CD AMIPRO 


Cancel 


Figure 7.1 PickFile in action. 


Edit-2 

In Chapter 6,1 introduced the Edit program as a simple editor. It had only the ability 
to edit and save a single data file using the name entered on the command line. Edit- 
2 improves on this by allowing the user to change the name to save the file to and 
load a new file into memory. Edit-2 also creates a backup file in the same subdirec¬ 
tory as the original data file but with a .BAK extension. This is created before the 
original data file is erased, so you’re never at risk of losing all your data. 

User interface 

Visually, not much has changed in this new version of the old Edit program. The but¬ 
tons are a little larger and two new buttons, Load New File and Save File As..., have 
been added. However, a significant portion of the code has been altered to accom¬ 
modate the changes. 

VX-REXX coding 

Adding a backup file is more complex than it first sounds. The actual process of cre¬ 
ating the file is trivial, as you can see in the Todo-1 program discussed earlier in this 
chapter. However, the process is much easier in Todo-1 because it has only one data 
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file that never changes its location, so it needs only one backup file. However, you 
can use Edit-2 to edit a wide variety of data files. These data files can be in the cur¬ 
rent subdirectory, a different subdirectory on the same drive, or even a different 
drive and subdirectory. Traditionally, the backup file has the same drive, subdirec¬ 
tory, and name, but with a .BAK extension. 

Edit-2 strips off the drive, subdirectory, and name of the file being edited and 
uses that to construct the name of the backup file. The VX-REXX code to do that is 
as follows: 

SetBackup: 

Drive = VRParseFileName(FileToEdit, D) 

Path = VRParseFileName(FileToEdit, P) 

Name = VRParseFileName(FileToEdit, N) 

Ext = VRParseFileName(FileToEdit, E) 

PARSE UPPER VAR Ext Ext . 

IF Ext <> "BAK" THEN BakFile = Drive !! !! Path !! "\" i! Name I! ".BAK" 

ELSE BakFile = Drive !! !! Path !! "\" !! Name !! " .BKA" 

return 


This code is called anytime the name of the file being edited changes. This can hap¬ 
pen with the Save File As... or Load New File buttons. Once the program knows how 
to find a backup filename, the following line is added to the SaveData subroutine to 
create a backup file: 


Okay = VRCopyFile(FileToEdit, BakFile) 


Because this command is executed before the original file is erased, one copy of the 
data always exists, so the most data the user can lose is the changes made since the 
last save. 

With this modification, the SaveData subroutine copies the existing data file (File¬ 
ToEdit) to the backup filename (BakFile), writes the data from memory to the data 
file, and closes the file. The code to do that is: 


SaveData: 

Okay = VRCopyFile(FileToEdit, BakFile) 
Okay = VRDeleteFile(FileToEdit) 

Output = VRGet("MLE_Edit", "Value") 
Okay = LineOut(FileToEdit, Output) 

Okay = LineOut(FileToEdit) 
return 


So all the program has to do to change the name of the data file in response to press¬ 
ing the Save Data As... button is to change the name of the FileToEdit and BakFile 
variables, and change the title in the main window since it shows the filename. The 
routine that does this is: 


PB_SaveAs_Click: 

Type = "S" 

CALL GetNewName 

IF NewName = "NO" THEN RETURN 

CALL SetBackup 
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WTitle = "Edit A File by Ronny Richardson " FileToEdit 

Okay = VRSet("Windowl", "Caption", WTitle) 

CALL SaveData 
return 


Since the only difference between a Save and Open VRFileDialog box is one flag, this 
subroutine and the PB_Load_Click subroutine change the value of that flag and call 
the same GetNewName subroutine to actually get the name. The second and third 
lines show this. If the user presses Cancel, the GetNewName will return a NO flag in 
New Name. When this happens, the user doesn’t want to save the file, so the fourth 
line returns without saving. The fifth line gets the new backup filename, the sixth 
and seventh lines change the title in the main window, and the seventh line calls the 
SaveData subroutine to actually save the data. The GetNewName subroutine han¬ 
dles getting a new name for both the Save File As... and Load New File buttons. Its 
code is as follows: 


GetNewName: 

NewName = "YES" 

OldName = FileToEdit 

FileToEdit = VRFileDialog("Windowl", "Save File As...", Type) 
IF FileToEdit = "" THEN 
DO 

FileToEdit = OldName 
NewName = "NO" 

END 

return 


The second line sets a variable to indicate that the filename has changed. The third 
line stores the old filename. The fourth line uses the VRFileDialog function to get a 
new filename, using the Type flag from the calling subroutine to indicate if it’s a Save 
or Open dialog box. If the user presses the Cancel button, no filename is returned, so 
lines six through nine check for this. When no name is returned, the original filename 
is restored and the variable flag is reset to show that a new name was not selected. 

This last error checking is required. Without it, the FileToEdit variable would be 
reset to null the first time a user clicked on the Cancel button. This wouldn’t create 
a problem until the program tried to either save to or or load from this null filename. 
At that point, the program would abort. It’s easy to miss this while testing your pro¬ 
grams, so be careful and make sure your program responds appropriately to press¬ 
ing the Cancel button. 

The original version of Edit created the FileToEdit variable in the LoadData sub¬ 
routine using the InitArg.l variable from the command line. This was moved to the 
Init subroutine, so the LoadData subroutine now simply loads the data using the file¬ 
name supplied to it in the FileToEdit variable. The code for the Load New File but¬ 
ton is: 


PB_Load_Click: 

Type = "0" 

CALL GetNewName 

IF NewName = "NO" THEN RETURN 

CALL LoadFile 


return 
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As you can see, it’s very similar to the PB_SaveAs_Click subroutine. It calls the Get- 
NewName subroutine to get a new filename and then calls the LoadFile subroutine 
to load the new file. If the user clicks on the Cancel button, this subroutine will skip 
loading the same file over again. 


Running the program 

Figure 7.2 shows Edit-2 running with a Save File As... dialog box currently active. 
While VX-REXX and OS/2 both come with nice editors, Edit-2 is nice because you 
can change the way it operates. 


Showing Error Messages with the VRMessage Function 

The VRMessage function is a handy way to display an error message and give the 
user several alternatives for resolving the problem. Just like the dialog box produced 
by the VRFileDialog function, the dialog box produced by the VRMessage function 
pops up over the existing code. Its syntax is: 


Button = VRMessage( object, message, [title], [icon], 
["Button, x" ], [default], [escape]) 


pr 'Edit A File bi 
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Figure 7.2 The Edit-2 program running and prompting the user for a new filename to save the current 
data file as. 
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where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop will be disabled. 

■ Message is the message to be displayed in the dialog box. 

■ Title is the title of the dialog box. 

■ Icon is a single character indicating the type of icon to display in the box. The pos¬ 
sible values are: E (an error icon), I (an informational icon), N (no icon), Q (a 
query icon), and W (a warning icon). 

■ Button.# is the stem variable that contains the button text. Button.0 must contain 
the button count, Button. 1 the text for the first button, Button.2 the text for the 
second button, and so on. If no buttons are specified, a single OK button will be 
displayed. 

■ Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

■ Escape is the button to assume was pressed if the user presses Escape. 

This function returns the number of the button that was pressed. If Escape is 

pressed, it returns a zero. 


ShowText 


The VRMessage function is a very handy way both to display error messages and ask for 
a response and to ask any question where the user needs to select from a limited num¬ 
ber of alternatives. ShowText is a simple program that lets you select the type of icon 
using RadioButton objects and then displays a VRMessage box. In most cases, you’ll 
want to predefine one RadioButon as preselected, which VX-REXX allows you to do. 
However, it isn’t required. ShowText takes advantage of this by not displaying an icon 
if no RadioButton is selected. Figure 7.3 shows this program running. The Click event 
for the top button controls the display of the VRMessage box. The code is as follows: 

/*:VRX */ 

PB_l_Click: 

Icon = "N" 

IF VRGet ("RB_1" , 11 Set" ) = 1 THEN Icon = "E" 

IF VRGet("RB_2","Set") = 1 THEN Icon = "I" 

IF VRGet ( "RB_3 " , "Set" ) = 1 THEN Icon = "Q" 

IF VRGet("RB_4","Set") = 1 THEN Icon = "W" 

Button.1 = "I Understand" 

Button.2 = "Tell Me More" 

Button.3 = "Cancel" 

Button.4 = "Start Over" 

Button.0 = 4 

ID = VRMessage("","This Is A Demonstration","VRMessage Box", Icon, "Button.",1, 3) 
return 
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Figure 7.3 The ShowText program in operation. 


The first five lines control which icon is used. The next four lines store the values for 
the four buttons. The tenth line stores the button count. The last operational line 
controls the display of the VRMessage box. 

Edit-3 

Although Edit-2 is a big improvement over Edit, it still allows you to quit or load an¬ 
other file without first confirming that you want to discard your edits on the current 
file. The VRMessage function gives you an excellent way to correct this problem. 

First, make the Change event for the MultiLine EntryField object call the Modified 
subroutine. This subroutine sets a flag to indicate that the data has been modified, 
plus it unhides a small Descriptive Text object that says “modified.” Since loading 
data into the MultiLine EntryField object triggers the Change event, this code is 
turned off while data is being loaded. This is handled in the same manner as with the 
Todo program from Chapter 6. The SaveData subroutine calls a similar subroutine, 
called UnModify, to turn the flag back off and hide the small Descriptive Text object. 
Once all this is completed, the routines that handle quitting and loading a new data 
file can tell if the data needs to be saved. 

For a prompt about saving the data when it has been modified, the following code 
is added to the top of the PB_Quit Click event: 

IF Modified = "YES" THEN 
DO 

Title = "Check Before Quitting" 

Message = "Data Not Saved, Quit Anyway?" 

Really = NotSaved(Title, Message) 

IF Really = 1 THEN RETURN 


END 
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The same code, with different messages, is added to the top of the Click event for the 
PB_Load object. The NotSaved user-defined function returns a one if the user de¬ 
cides to cancel the action (not quitting or not loading a different file) or a two if the 
user decides to continue even though the data hasn’t been saved. The NotSaved user 
defined function is: 


NotSaved: 

PROCEDURE 
Title = Arg(l) 

Message = Arg(2) 

Button.0 = 2 
Button.1 = "Cancel" 

Button.2 = "Abandon Changes" 

Okay = VRMessage("Windowl", Message, Title, "W", "Button.", 1, 1) 
return okay 

You might want to add a third button to save the data before completing the re¬ 
quested action. Figure 7.4 shows Edit-3 running with one of its VRMessage dialog 
boxes showing. 


Todo-2 


The Todo-1 program discussed in the previous chapter can take advantage of VRMes¬ 
sage boxes in two different ways. First, erasing a to-do item should be a little harder 
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Figure 7.4 If you try to quit or load another file before the current data has been saved, Edit-3 will warn 
you and give you the option to change your mind. 
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than just clicking on an Erase button because data is permanently lost. Each of the 
Erase buttons calls the Erase subroutine, and adding the following code to the top of 
the Erase subroutine causes it to ask the user for confirmation before erasing an item: 

Button.0 = 2 
Button.1 = "No" 

Button.2 - "Yes" 

Okay = VRMessage("Windowl", "Erase This Todo Item?", "Erase Check", "Q", 
"Button.", 1, 1) 

IF Okay = 1 THEN RETURN 

It doesn’t ask for confirmation on done items since it’s fairly common to complete 
tasks on your to-do list, and this data is stored in a completion file rather than just 
being erased. However, very similar code would allow you to require confirmation for 
done items as well. 

Todo-1 already tracks to see if the data has been modified using the Modified vari¬ 
able, so adding confirmation before quitting with unsaved data is fairly easy. Since 
there’s only one Quit button, the code that follows was added to its Click event: 

IF Modified = "YES" THEN 
DO 

Button.0 = 2 
Button.1 = "No" 

Button.2 = "Yes" 

Okay = VRMessage("Windowl", "Todo List Not Saved! Quit Anyway?", 

"Quit Check", "Q", "Button.", 1, 1) 

IF Okay = 1 THEN RETURN 

END 

Figure 7.5 shows this version of Todo running with one of its dialog boxes displayed. 


Showing Multiple Line-Error Messages with VRMessageStem 

If you have a long message to display, using the VRMessage function can be cumber¬ 
some. The VRMessageStem function is much easier to use for long messages; you 
just store the message, line by line, in a stem variable. Otherwise, the VRMes¬ 
sageStem function works like the VRMessage function. Its syntax is as follows: 

Button = VRMessageStem(object, "Message.x", [title], [icon], 

["Button.x"] , [default], [escape]) 


where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop will be disabled. 

■ Message is the name of the stem variable that contains the message. Message.0 
must contain the count of the lines, Messaged the first line of the message, Mes¬ 
saged the second line, and so on. 

■ Title is the title of the dialog box. 
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f&i Todo Version 82 by Bonny Richardson 
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Figure 7.5 If you try to quit without saving your data, Todo will warn you. It will also ask for confirmation 
before erasing a to-do item. 


■ Icon is a single character indicating the type of icon to display in the box. The pos¬ 
sible values are: E (an error icon), I (an informational icon), N (no icon), Q (a 
query icon), and W (a warning icon). 

■ Button is the stem variable that contains the button text. Button.O must contain the 
button count, Button. 1 the text for the first button, Button.2 the text for the sec¬ 
ond button, and so on. If no buttons are specified, a single OK button is displayed. 

■ Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

■ Escape is the button to assume was pressed if the user presses Escape. This func¬ 
tion returns the number of the button that was pressed. If Escape is pressed, it will 
return a zero. 

Showing a Message and Getting a Long Response with VRPrompt 

The VRPrompt function is used to display a prompt to the user in a dialog box and 
then obtain a lengthy response. For example, it might ask the user’s name or ad¬ 
dress. It also has the option of displaying buttons and returning the button that was 
pushed. Its syntax is: 


Q3 -imf 


51 ~~m' oH 

33 m .,. 



Done 


Done 


r m . (Si 2 a hi; 


Done 


Er; 


Todo List Hot Saved! Quit Anyway? 




rash Pickup 


Ning 


Button = VRPrompt( object, prompt, Contents, [title], 
["Button, x" ], [default], [escape]) 
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where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop will be disabled. 

a Prompt is the message to display for the user. 

m Contents is the name of the variable to receive the information the user types into 
the dialog box. This is required because the function itself returns the number of 
the button that’s pushed. 

m Title is the title of the dialog box. 

■ Button is the stem variable that contains the button text. Button.O must contain 
the button count, Button. 1 the text for the first button, Button.2 the text for the 
second button, and so on. If no buttons are specified, a single OK button will be 
displayed. 

■ Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

Escape is the button to assume was pressed if the user presses Escape. 


Prompt 


Prompt is a simple program that asks users for their first and last name and then dis¬ 
plays that information in a Descriptive Text object. Figure 7.6 shows this program in 
operation. The VRPrompt function is controlled by the Click event of the top button. 
Its code is: 

/*:VRX */ 

PB_l_Click: 

Button.O = 2; Button.1 = "OK"; Button.2 = "Cancel" 

Button = VRPrompt("", "Please Enter Your First Name",, 

First, "Getting First Name", "Button.", 1, 2) 

Button = VRPrompt("", "Please Enter Your Last Name",, 

Last, "Getting Last Name", "Button.", 1, 2) 

First = "First Name Is:" First 
Last = "Last Name Is:" Last 
Message = First ! ! "d"x ! ! Last 
Okay = VRSet(DT_1, "Caption", Message) 
return 


The first line stores the values to the buttons. The second and third lines are one log¬ 
ical line that asks users for their first name. The fourth and fifth lines are one logical 
line that asks users for their last name. The next three lines create a single message, 
and the last line displays this message in a Descriptive Text object. 


Todo-3 


The VRPrompt function offers an excellent way to enter new to-do items and asso¬ 
ciated priorities into the to-do program. The text goes into the VRPrompt message 
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Prompt Demonstration by Ronny Richardson 


Please Enter Your Last Name 
I Richar dson 


OK 1! Cancel 


Figure 7.6 The Prompt program running. 


area, and the priority can be obtained by giving the user a different button to push 
for each priority, plus one to cancel data entry. A new button is added to the bottom 
of the program to add new items, and the modified Descriptive Text object is moved 
to the bottom right corner of the screen to make room. The new button calls the 
NewTodoItem subroutine, which is as follows, with line numbers added: 


1. NewTodoItem: 

2. Item = Todo.O + 1 

3. Prompt = "Enter New Todo Item" 

4. Title = "New Todo Item" 

5. Buttons.0=4 

6. Buttons.1 = "High Priority" 

7. Buttons.2 = "Medium Priority" 

8. Buttons.3 = "Low Priority" 

9. Buttons.4 = "Cancel" 

10. Priority.Item = VRPrompt("Windowl", Prompt, Todo.Item, Title, 

"Buttons.", 4, 4) 

11. IF Priority.Item = 4 THEN RETURN 

12. Todo.O = Item 

13. CALL SetTodoItems 

14. CALL Modified 

15. return 

Line 2 creates a new variable to be used as the tail of the stem variables for this new 
to-do item. Lines 3 and 4 create the prompt and title for the VRPrompt function. Lines 
5-9 create the buttons. Note that the numbers of the high-, medium-, and low-prior¬ 
ity buttons correspond to the numbers in the data file. As a result, they can be used 
without translation. Line 10 calls the VRPrompt function. If the user cancels the ac¬ 
tion, line 11 exits the subroutine without creating the to-do item or priority. Line 12 
stores the text to a variable. The priority is automatically stored by the VRPrompt 
function on line 10. Line 13 calls on the SetTodoItems subroutine to redisplay the 
screen. Since the new item is initially appended to the end of the list, this is required 
only when there’s less than a full screen of to-do items to display. Finally, line 14 calls 
on the Modified subroutine to mark the data as modified because a new to-do item has 
been added. Figure 7.7 shows a to-do item being added while the program is running. 
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Figure 7.7 By using the VRPrompt function, Todo finally has a method with which to enter new to-do 
items. 


Summary 

The VRFileDialog allows you to obtain a filename from the user. The VRMessage and 
VRMessageStem functions display a message to the user and return the button that’s 
clicked. The VRPrompt displays a message to the user and returns both the button 
that’s clicked and the single line of entered text. The VRFileDialog, VRMessage, 
VRMessageStem, and VRPrompt dialog boxes pop up over the existing window with¬ 
out the programmer having to manage the different windows. 

PickFile uses the VRFileDialog VX-REXX function to get a filename from the user. 
ShowText uses the VRMessage VX-REXX function to display a message. Edit-3 im¬ 
proves on Edit-2 by using the VRMessage VX-REXX function to warn the user before 
discarding modifications to a file. Todo-2 improves on Todo-1 by using the VRMes¬ 
sage VX-REXX function to warn the user before erasing a to-do item. Prompt uses 
the VRPrompt VX-REXX function to ask the user’s name. Todo-3 improves on Todo- 
2 by using the VRPrompt VX-REXX function to get new to-do items from the user. 












Chapter 

8 

Selecting Values from a List 


In Chapter 7, you saw how to have the user select from a list of items using VX-REXX 
functions. Some of these functions put buttons on the screen for the user to click on 
and others put a list of files on the screen for the user to pick from. In this chapter, 
you’ll continue to look at having the user select from lists. In this chapter, however, 
you’ll create the lists yourself rather than simply using a few buttons or having VX- 
REXX list the available files. 

ListBox Object 

The ListBox object presents a list of items inside a box with a movable cursor. As the 
user moves the cursor up and down, the currently selected item in the list is made 
available to the program. Consider the following example program. 


Listbox 


Listbox is a demonstration program that presents a list of all 16 possible background 
colors in a ListBox object. As you scroll through the list, the background color of the 
ListBox object changes to match the currently highlighted color. When you double¬ 
click on a color, that color is made the foreground color. (At that point, the color will 
be both the foreground and background color, so the list won’t be visible until you 
move the cursor after double-clicking.) Not all combinations of colors are visible on 
all screens, and the list is never visible when the foreground and background colors 
are the same. Click on the quit button to exit the program. 

Figure 8.1 shows the user interface for Listbox. Three issues are important with 
this program: 


B How do you get the list into the ListBox object? As you can see from Figure 8.1, the 
list is not displayed during the design phase. 
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Figure 8.1 The user interface for the Listbox program. 


H How does the program act on the list as the user highlights each item? Since the 
background is going to change each time the user highlights a new color, the pro¬ 
gram must act each time the cursor is moved. 

■ How does the program act on the list when the user double-clicks on an item in the 
list? 


Inserting the list 

Since the text is not visible in Figure 8.1, you know that a tab in the object’s Property 
Notebook hasn’t been used to insert the text. The process of inserting text has two 
steps. First, a stem variable is created, where Stem.O contains the item count and 
each stem variable, Stem.l, Stem.2 and so on, contains the text—one stem variable 
per line. This is handled in the Init subroutine and the code is as follows: 


Colors.0 = 
Colors.1 
Colors.2 
Colors.3 
Colors.4 
Colors.5 
Colors.6 
Colors.7 
Colors.8 ■ 
Colors.9 
Colors.10 


16 

"Black" 
"Blue" 
"Brown" 

"Cyan" 
"DarkBlue" 
"DarkCyan" 
"DarkGray" 
"DarkGreen 
"DarkPink" 

: "DarkRed" 
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Colors.11 
Colors.12 
Colors.13 
Colors.14 
Colors.15 
Colors.16 


'Green" 

1 PaleGray 
' Pink" 
'Red" 
White" 
Yellow" 


After this code runs, the stem variable Colors contains a list of 16 colors. The next 
step is to load this stem variable into the ListBox object. The code to do that is also 
in the Init subroutine and is as follows: 

Okay = VRSet("LB_1", "Sort", "None") 

Okay = VRMethod( "LB_1", "AddStringList", "Colors." ) 

The first line tells VX-REXX not to sort the list into alphabetical order. (The default 
is to sort the list.) The second line uses the AddStringList Method of the VRMethod 
VX-REXX function to insert the list into the ListBox object. The program performs 
this in the Init section since the contents of the list never changes. 

If you want to construct the list of items one at a time, you can use the 
AddString function to insert the list items individually. AddString also allows you 
to control the position of each item in the list. Of course, by controlling the posi¬ 
tion of each data element in the stem variable, you control the order using the 
AddStringList method. 

Cursor movement 

The behavior of the ListBox object is slightly different than the behavior of the other 
objects you’ve looked at. Each time the cursor is moved, a Click event is generated, 
even if the mouse isn’t clicked or Return pressed. By defining some activity for the 
Click event, the program can take action each time the cursor is moved. Listbox uses 
this to change the background color each time the cursor is moved. The code for the 
Click event is: 

LB_l_Click: 

Okay = VRMethod( "LB_1", "GetSelectedList", "selects." ) 

Picked = Selects.1 

Okay = VRSet("LB_1", "BackColor", Colors.Picked) 

return 


The second line reads the position of the selected item in the list and stores it to the 
Selects. 1 stem variable. The third line transfers this to a nonstem variable, and the 
fourth line uses this variable to retrieve the color from the list and uses the VRSet 
function to change the background color. 

Double-clicking 

Any time the user presses Return on a highlighted item or double-clicks on an item 
with the mouse, VX-REXX generates a Doubleclick event for the ListBox object. 
Listbox uses this Doubleclick event to change the foreground color. The code is very 
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Figure 8.2 The Listbox program in operation. 


similar to the Click event code shown previously, only the foreground color is 
changed. The Doubleclick event code is: 


LB_l_DoubleClick: 
Okay = VRMethod( 
Picked = Selects. 
Okay = VRSet("LB_ 
return 


"LB_1", "GetSelectedList", "selects. 
1 

1”, "ForeColor", Colors.Picked) 


) 


Figure 8.2 shows Listbox running. 


Listhox2 

While Listbox acted on the items in the list, there is no requirement to do so. In fact, 
the ListBox object does a good job of displaying an ASCII file, as Listbox2 illustrates. 
When you first start Listbox2, it prompts you for the name of an ASCII file to list. Any 
filename entered on the command line is ignored; however, this would be a simple 
addition. Once the file has been selected, Listbox2 displays the contents of the file in 
a ListBox object. The filename is displayed at the bottom in a Descriptive Text ob¬ 
ject, and there are buttons to load another file and quit the program. 

The Init section of Listbox2 calls on the FillListBox subroutine to pick a filename 
and then insert the text into the ListBox object. The button to load another file also 
calls this subroutine. The FillListBox subroutine is as follows, with line numbers 
added for easy reference: 


1. FillListBox: 

2. Okay = VRMethod("LB_1", "Clear") 

3. Okay = VRSet("LB_1", "Sort", "None") 

4. File = VRFileDialog(VRWindow(),"File to list", "Open") 

5. Okay = VRSet("DT_1", "Caption", File) 

6. String.0 = 0 
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7. DO WHILE Lines(File) > 0 

8. String.0 = String.0 + 1 

9. I = String.0 

10. String.I = Lineln(File) 

11. end 

12. Okay = VRMethod("LB_1","AddStringList", "String") 

13. return 


Line 2 clears out the contents of the ListBox object. This isn’t required initially when 
the subroutine is called by the Init section, but after that the ListBox object will al¬ 
ready have a list in it and the AddStringList command will append the new contents 
onto the existing list. Line 3 turns off sorting in the ListBox object, so the ASCII file 
is displayed in the proper order. Line 4 uses the VX-REXX VRFileDialog function to 
get the name of a file, and line 5 displays this name in the Descriptive Text object. 
Lines 6-11 loop through the file, reading in the lines and storing them and a count to 
a stem variable. Finally, line 12 places this text into the ListBox object. 

No Click or Doubleclick events are defined for this ListBox object. That way the 
user can scroll through the file looking at its contents without triggering any action 
by the program. Figure 8.3 shows the program being used to list a VX-REXX pro¬ 
gram file. 


ComboBox Object 

The ComboBox object is a combination of an EntryField object and a ListBox object. 
It displays a list of items for users to select from, like a ListBox object. Unlike a List- 
Box object, users can enter their own text if none of the selections in the list matches 
the response they want to provide, just like an EntryField object. 


Listbox2 by Ronny Richardson 


/*:VRX 


Main 


/* Main 
*/ 

Main: 

Process the arguments. 

Get the parent window. 

*/ 

parse source . calledAs . 
parent = "" 
argCount = arg() 
argOff = 0 

if( calledAs \= “COMMAND'* )then do 
if argCount >= 1 then do 
parent = arg(1) 
argCount = argCount - 1 
argOff = 1 
end 
end 

initArgs.8 = argCount 

if( argCount > 8 )then do i = 1 to argCount 
InitArgs.i = arg( i + argOff) 
end 

drop calledAs argCount argOff 


C:\GS2\VXREXX\EXAMPLES\LISTBOX2\LISTBGX2.VRX 


Figure 8.3 Listbox2 in operation, showing a file. 
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Survey-3 

Survey-3 uses five ComboBox objects to ask users questions about their computers. 
Once the done button is clicked, the five responses are displayed in a Descriptive 
Text object, the five ComboBox objects are returned to their default value, and the 
program is ready to receive another response. 

The Init section creates variables containing the name of each ComboBox ob¬ 
ject and then calls on the subroutines SetQuestionl through SetQuestion5 to 
arrange each ComboBox object. SetQuestionl is as follows, with line numbers 
added: 


1. 

SetQuestionl: 



2 . 

Answers.1.0 = 

5 


3 . 

Answers.1.1 = 

"8088" 


4. 

Answers.1.2 = 

"80286" 


5. 

Answers.1.3 = 

"80386" 


6 . 

Answers.1.4 = 

"80486" 


7 . 

Answers.1.5 = 

"80586" 


8. 

Okay = VRSet(Boxl, "Sort", 

"None") 

9. 

Okay = VRSet(Boxl, "Value", 

. Answers.1.4) 

10. 

Okay = VRMethod(Boxl, "AddStringList", " 

11. 

return 




Lines 2-7 create the stem variable that contains the list of responses for the 
ComboBox object. Line 8 turns off sorting for this ComboBox object. Line 9 de¬ 
fines a default response for the ComboBox object. If a default isn’t specified, the 
top of the ComboBox object will be blank when it’s first displayed on the screen. 
Line 10 places all the responses into the ComboBox object. The other four Com¬ 
boBox objects are defined in a similar fashion by SetQuestion2 through SetQues- 
tion5. 

The Done subroutine is called by the done button. It first displays the responses in 
the Descriptive Text object and then resets the default values in the ComboBox ob¬ 
jects. Its code is as follows, with numbers added: 

1. Done: 

2. CPU = VRGet(Boxl, Value) 

3. Memory = VRGet(BOX2, Value) 

4. HardDisk = VRGet(Box3, Value) 


5. 

Screen 

= VRGet(Box4, Value) 



6 . 

Case 

= VRGet(Box5, Value) 



7 . 

Data = 


"CPU Type. 

. ." CPU !! Return 

8. 

Data = 

Data 

! ! "Memory Amount... 

. . " Memory ! ! 

Return 

9 . 

Data = 

Data 

!! "Hard Disk Size.. 

. ." HardDisk 

!! Return 

10 . 

Data = 

Data 

!! "Screen Type. 

. ." Screen ! ! 

Return 

11. 

Data = 

Data 

!! "Case Type. 

. ." Case 



12. Okay = VRSet(DTJResults, Caption, Data) 

13. Okay = VRSet(Boxl, "Value", Answers.1.4) 

14. Okay = VRSet(Box2, "Value", Answers.2.4) 

15. Okay = VRSet(Box3, "Value", Answers.3.1) 

16. Okay = VRSet(Box4, "Value", Answers.4.4) 

17. Okay = VRSet(Box5, "Value", Answers.5.3) 

18. return 
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Lines 2-6 read the responses from the five ComboBox objects. Lines 7-11 create 
a variable containing text and the responses from the five ComboBox objects. The 
Return variable is created by the Init section and contains the value ‘Od’x. As you 
might recall from an earlier discussion, the Descriptive Text object needs only 
‘Od’x for the Return and not the full ‘OdOa’x. Line 12 displays this variable in the 
Descriptive Text object. Finally, lines 13-17 reset the ComboBox objects to their 
default values. 

Figure 8.4 shows Survey-3 running after one set of values has been entered. Note 
that the hard-disk size that was entered doesn’t match any of the preprogrammed 
values. This illustrates that a ComboBox object allows you to enter a value not in the 
preprogrammed list. 


DropDown ComboBox Object 

The ComboBox objects in Survey-3 take up a lot of screen real estate, as you can see 
from Figure 8.4. Most of the time it isn’t necessary to show the entire list of possible 
values. In fact, it’s necessary only when the user is entering data into that particular 
ComboBox object and wants to select from a list. The DropDown ComboBox object 
reduces the screen real estate required by hiding the list under normal operation 
and showing only the top of the ComboBox object where the selected data item is 
displayed. Click on the down arrow and the entire list is displayed. If it won’t fit in 
the allocated space, then a scroll bar is used. Once you’ve selected an item from the 
list, the list is hidden again. 


Survey Version 3 by Ronny Richardson 
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Figure 8.4 Survey-3 in operation. Note that the hard-disk size doesn’t match any of the items in the list. 
This illustrates that the ComboBox object lets the user enter custom values. 
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Survey-4 is a version of Survey-3, modified to use DropDown ComboBox objects 
rather than ComboBox objects. Figure 8.5 shows its user interface. I had to make 
only three changes to Survey-3. They are: 

■ Replacing the ComboBox objects with DropDown ComboBox objects. 

■ Changing the name of the boxes in the Init section. 

■ Moving the questions to the top of the DropDown ComboBox objects. This isn’t re¬ 
quired, but having them at the bottom leaves them a long way from the EntryField 
object. 

Figure 8.6 shows Survey-4 in operation with one set of values entered. Note that the 
hard-disk size entered doesn’t match any of the preprogrammed values. 


Summary 

The ListBox object presents a list of items inside a box with a movable cursor. As the 
user moves the cursor up and down, the currently selected item in the list is avail¬ 
able to the program. The ComboBox object is a combination of an EntryField object 
and a ListBox object. It displays a list of items for the user to select from, and users 
can enter their own text if none of the selections in the list matches the response 
they want to provide. The DropDown ComboBox object is a specialized ComboBox 
object that doesn’t display the list of items unless the user clicks on an arrow. The 



Figure 8.5 The user interface for the Survey-4 program. 
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Figure 8.6 Survey-4 in operation. Note that the DropDown ComboBox objects take up much less space 
on the screen than the ComboBox objects. 


Listbox program uses a ListBox object to let the user select the background and 
foreground colors. 

Listbox2 uses a ListBox object to display an ASCII file. Survey-3 uses a ComboBox 
object to create a survey. Survey-4 modifies Survey-3 to use DropDown ComboBox 
objects in the survey. 
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Dressing Up Your 
Programs with Pictures 


All of the objects you’ve seen so far use words when they need to communicate with 
the user. As you might expect, since OS/2 is a graphical environment, VX-REXX has 
objects that communicate with pictures rather than words. The PictureBox object 
displays a bitmap or resource image much like a Descriptive Text object displays 
text. The Image PushButton object looks like and functions like a PushButton object 
except it displays an image inside the button rather than text. And the Image Ra- 
dioButton object works just like a RadioButton object only it displays an image 
rather than text. 

PictureBox Object 

The PictureBox object is much like a Descriptive Text object, but it displays a graph¬ 
ical image rather than text. The image isn’t displayed at design time, only at runtime. 
The image is loaded from disk each time the program is executed, so the external im¬ 
age file must be maintained with the program. This also means anyone running your 
program will be able to modify the appearance of that program by editing the 
bitmapped image. Later, you’ll see how to avoid this potential problem. The Picture- 
Box object can display the following types of images: 

Bitmap files. These usually have a .BMP extension. 

Icons. These are small files that typically have an .ICO extension. 

Resource identifiers. These are bitmap images or icons stored inside a dynamic link 
library (DLL) or a program (.EXE) file. 
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image PushButton Object 

The Image PushButton object is a PushButton object that simply displays an im¬ 
age rather than text. Just like the PictureBox object, the image can be a bitmap 
file, icon, or resource identifier. The image is displayed during design, but it’s 
loaded from disk at runtime, so a separate image file for the user to modify must 
be maintained. 

image RadioButton Object 

The Image RadioButton object is a RadioButton object that displays an image rather 
than text. Just like the PictureBox object and Image PushButton object, the image 
can be a bitmap file, icon, or resource identifier. The image is displayed during de¬ 
sign, but it’s loaded from disk at runtime. A separate image file, therefore, must be 
maintained; the user can modify this image. The following programs show how to use 
these objects. 


Pictures 

Pictures is a demonstration program that displays the volume label, amount of 
space in use, amount of free space, and current subdirectory of either the A, B, or 
C drive. Figure 9.1 shows the user interface for Pictures. Note that the Picture- 
Box object appears empty even though a path to its picture has already been de¬ 
fined. Also note that the Image RadioButton objects have only the image; there’s 
no circle that blackens when it’s selected. Instead, the picture changes to reverse 
colors when selected. As a result, you must be careful in your selection of pictures 
to make sure they present sufficient contrast to the user so the user will know 
which image is selected. 

Figure 9.2 shows Pictures in operation. The PictureBox object doesn’t change 
while the program is running. The Image PushButton object Click event simply is¬ 
sues a CALL Quit command to exit the program. The bulk of the program is taken 
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Figure 9.1 The Pictures interface. Note that the image for the PictureBox object isn’t displayed. 











Dressing Up Your Programs with Pictures 111 



Drive To Report On Is C 


Vo Iuse Label.......GATEWAY 

Current Directory..Root 

Space In Use...396296192 

Space Free.........127696896 


M 


kflGi 




W-& 

. - . , i ..V —~ « f, 

2"*- 1 X * ' . 


l '*< 


Figure 9.2 The Pictures program in operation. 


care of by the three Image RadioButton objects. Each calls the Disk subroutine and 
passes it either an A, B, or C to indicate the disk to be processed. The Disk subrou¬ 
tine is shown in Figure 9.3. 


ViewBmp 

ViewBmp functions as a file viewer for bitmapped images. The VRFileDialog VX- 
REXX function selects a bitmapped file for viewing, and ViewBmp displays the im¬ 
age in a PictureBox object. Initially, the PictureBox object isn’t assigned an image to 
display. That is handled by the Click event of the Load button. The subroutine is as 
follows: 


PB_Load_Click: 

Picture = VRFileDialog, "Load Picture", "0", "*.BMP") 

Okay = VRSet("Pict_l", "PicturePath", Picture) 

Okay = VRSet("DT_Name", "Caption", Picture) 
return 


In the second line, VRFileDialog has the user select a bitmapped image. Note that 
the *.BMP file mask is used. The third line causes the PictureBox object to display 
the image. The PicturePath property of the PictureBox object is similar to the Cap¬ 
tion option of the Descriptive Text object. The fourth line places the name of the file 
in a Descriptive Text object at the bottom of the screen. Figure 9.4 shows ViewBmp 
displaying a screen shot from later in this book. 

This PictureBox object is configured to expand or contract to fit the given image. 
It’s also possible to configure the PictureBox object to stay the same size. 


Viewlcon 

Viewlcon functions as an icon viewer, displaying all the icons in the current subdi¬ 
rectory along with their names. It has room for 49 icons. If there are fewer than 49 
icons, the remaining slots (PictureBox objects) are hidden. If there are more than 49 
icons, scrolling is supported for the remaining icons. The Forwards button is dis¬ 
played only when it’s possible to scroll forwards, and the Backwards button is dis¬ 
played only when it’s possible to scroll backwards. 
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VX-Rexx Code 

Explanation 

Disk : 

The name ot the subroutine. 

This subroutine gets information 
on the specified disk drive. 

PROCEDURE 

Hide all the variables ot the 
main program from this subrou¬ 
tine. 

Report = 'Od'x || 'Od'x || 'Od'x || "Working" 

Create a variable containing 
three Returns and a message that 
the program is working. 

Okay = VRSet(DT_1, Caption, Report) 

Display this message variable in 
the Descriptive Text box. 

Report = "" 

Reset the variable. 

Drive = Arg(l) 

Obtain the drive to process from 
the first argument. 

Directory = VRCurrDir(Drive) 

Store the current subdirectory ot 
the drive to a variable. 

IF Directory = "" THEN Directory = "Root" 

Since the backslash is stripped 
off the root directory it appears 
blank, so if the variable is blank 
then store the word Root to the 
variable. 

Label = VRDiskLabel(Drive) 

Store the volume label ot the 
drive to a variable. 

SpaceUsed = VRDisklnfo(U, Drive) 

Store the amount of space used 
on the drive to a variable. 

SpaceFree = VRDisklnfo(F, Drive) 

Store the free space on the drive 
to a variable. 

IF SpaceFree = -1 THEN 

DO 

If the free space is reported to be 
-1, then the drive is not ready, so 

Label = "Drive Not Ready" 

reset all the variables to reflect 

Directory = "Drive Not Ready" 

SpaceUsed = "Drive Not Ready" 

SpaceFree = "Drive Not Ready" 

this. 

END 


Report = Report || "Drive To Report On Is" 

Construct a report variable. 

Drive | j 'Od'x || 'Od'x 


Report = Report | | "Volume Label. " | | 


Label || 'Od'x 


Report = Report || "Current Directory.." 


Directory || 'Od'x 


Report = Report | | "Space In Use. " | 


SpaceUsed || 'Od'x 


Report = Report | "Space Free. " | 


SpaceFree 


Okay = VRSet(DT_1, Caption, Report) 

Display this report variable in 
the Descriptive Text box. 

return 

Exit the subroutine. 


Figure 9.3 The Disk subroutine, which creates the disk-drive report in Pictures. 
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Figure 9.4 The ViewBmp program in operation, displaying a bitmapped image from later in this book. 


Viewlcon is too large to run on a VGA display. If you have a VGA monitor, there’s a 
36-icon version of Viewlcon called VI-VGA on the CD-ROM. Other than working with 
fewer icons, it’s identical to Viewlcon. 

None of the PictureBox objects have pictures assigned to them at design time. The 
Init subroutine calls on the GetAllIcons subroutine to load the names of all the .ICO 
icon files from the current subdirectory into memory. That subroutine is: 


GetAllIcons: 

CALL RxFuncAdd 'SysLoadFuncs 1 , 'RexxUtil', 
CALL SysLoadFuncs 

CALL SysFileTree "*.ICO", 'Matching.', 'FO' 


return 


SysLoadFuncs' 


Since there isn’t a VX-REXX function for loading all the matching filenames into 
memory, it loads and then uses the RexxUtil SysFileTree external REXX function. In 
order for this program to run, you must have RexxUtil (an OS/2 installable option) 
installed on your system. 

Once the icon names are loaded into memory, the Init subroutine calls on the 
Showlcons subroutine to display the subroutines. It passes the subroutine the num¬ 
ber 1 as the starting point and the Matching.!) stem variable (which contains a count 
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of the icons) as the last possible icon to display. That subroutine is as follows, with 
line numbers added: 


1. 

Showlcons: 



2 . 

FirstShow = Arg(l) 



3 . 

LastShow = Min(Arg(2), FirstShow + 

48) 


4. 

Kount = 0 



5 . 

DO I = FirstShow TO LastShow 



6. 

Kount = Kount + 1 



7 . 

IconBox = "Icon_" !! Kount 



8 . 

TextBox = "DT_" !! Kount 



9. 

Okay = VRSet(IconBox, "Visible", 

1) 


10. 

Okay = VRSet(TextBox, "Visible", 

1) 


11. 

Okay = VRSet(IconBox, "PicturePath", 

Matching.I) 

12. 

Name = VRParseFileName(Matching. 

I, " 

N") ! ! ".ICO 

13 . 

Okay = VRSet(TextBox, "Caption", 

Name) 

14. 

END 



15. 

IF Kount <49 THEN 



16. 

DO I = Kount + 1 TO 49 



17 . 

IconBox = "Icon_" !! I 



18. 

TextBox = "DT_" ! ! I 



19. 

Okay = VRSet(IconBox, "Visible", 

0) 

20. 

Okay = VRSet(TextBox, "Visible", 

0) 

21. 

END 



22. 

return 




Lines 2-3 load the arguments into variables. Since there are only 49 slots, the Last- 
Show variable has to be calculated to make sure it doesn’t exceed that limit. Line 4 
establishes a counter variable. Line 5 loops through all the icons to be displayed. 
Line 6 increments a counter. Lines 7-8 create variable names for the objects to use. 
Lines 9-10 make the objects visible. Line 11 displays the picture. Line 12 strips the 
name of the icon from its full path and adds the .ICO extension, and then line 13 dis¬ 
plays that name. When not all of the PictureBox objects are used to display icons, 
lines 15-21 loop through and hide the PictureBox objects and associated Descriptive 
Text objects that aren’t used. 

After this, the Keys subroutine is called to figure out which of the Forwards and 
Backwards PushButton objects should be displayed. That subroutine is as follows: 


Keys : 

IF Matching.0 > LastShow THEN Okay = VRSet("PB_Forwards", "Visible", 1) 
ELSE Okay = VRSet("PB_Forwards", "Visible", 0) 

IF FirstShow > 1 THEN Okay = VRSet("PB_Backwards", "Visible", 1) 

ELSE Okay = VRSet("PB_Backwards", "Visible", 0) 

return 


The Click events for the Forwards and Backwards PushButton objects simply incre¬ 
ment or decrement the starting position and then call the Showlcons and Keys sub¬ 
routines. Figure 9.5 shows Viewlcon being used to display icons. Note that all the 
slots are used and the Forwards button is displayed. 
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Figure 9.5 The Viewlcon program, displaying a subdirectory of icons. There are more icons to display, so 
the Forwards button is visible. 


Resource Binding 

I’ve mentioned that using icons and bitmapped images in your program has two 
drawbacks: you have to make sure the images are available to the user when the 
program is run, and the user can alter those images. As it turns out, Watcom 
thought of that and has a file called VXREZ.ZIP to correct the problem. This sec¬ 
tion will show you how to perform resource binding with VXREZ. VXREZ is in¬ 
cluded on the CD-ROM. 

Resource binding is the process of bundling the icons and bitmapped images 
needed by a program into the .EXE file itself. Once the resources are bound into the 
program, you don’t have to include them with your program so the user can’t modify 
them. And since the images are inside the program file, they’re always available to 
the program. 

In an empty part of the window, click with the right mouse button to bring up the 
pop-up menu. Once VXREZ has been properly installed, that menu will have an Edit 
Resources... option, as shown in Figure 9.6. Clicking on that option will bring up the 
VXREZ mini-editor, shown in Figure 9.7. You can use this editor to enter the names 
of the resources used by VXREZ. You must save your program at least once before 
using VXREZ so the program has a name. 
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Properties 
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Help 

Paste 

Menu editor... 

Tab editor... 

Edit resources... 


Figure 9.6 VX-REXX adds a 
new Edit Resources...menu 
option to the pop-up menu. 



Figure 9.7 The VXREZ main window is a mini-editor where you can 
enter information on the resources in your program. 

Select Insert from the Edit menu and VXREZ will bring up a dialog box for you to 
enter resources into, as Figure 9.8 shows. You’ll rarely use the Preload, Moveable, or 
Discardable options, so you can ignore them. The number is a user-defined number 
that must be an integer from 1 to 65,535, and it must be unique for each resource. 
The process is fairly simple and once you’re familiar with the process you might want 
to enter the information directly into the VXREZ editor and bypass this dialog box. 

OS/2 includes a resource compiler as one of its standard utilities, so you don’t need 
any special software. Once all the resources have been entered, select the Save and 
Compile option from the File menu. This saves the resource file in the same direc¬ 
tory as your project and runs the OS/2 resource compiler. The resource compiler 
converts the file created by VXREZ into a compiled .RES file that contains all the re¬ 
sources that will be bound to your .EXE program file. 

Now go into the property notebook for the object that uses the bitmapped images 
and change the references from filenames to the number you assigned to that re¬ 
source, only precede it with a number sign (#). Bound resources don’t show up in 
the design phase or debugging phase, but a small symbol does appear to let you 
know the object uses bound resources, as shown in Figure 9.9. 

Compile your program normally, except that before the file dialog appears asking 
you to name the executable, you’ll be told that resources are being bound. The .EXE 
program doesn’t need or use the bitmapped image files. 
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Figure 9.8 When you select Insert from the Edit menu, VXREZ dis¬ 
plays a dialog box where you can enter information on your program’s 
resources. 
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Figure 9.9 While the icons themselves don’t show in the design phase after using VXREZ, your program 
does display a simple icon to let you know that bound resources are being used. The program appears nor¬ 
mally while running. 
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If you’re planning on using bitmapped images in your program, learn to use 
VXREZ. It makes distributing your programs safer and easier. 


Summary 

The PictureBox object lets you display a bitmapped image. That image isn’t dis¬ 
played in the design phase and is visible only at runtime. The Image PushButton and 
Image RadioButton objects function just like PushButton and RadioButton objects, 
only they display an image rather than text. The images for all three objects is loaded 
at runtime. You can use VXREZ to bind icons and bitmapped images into a program, 
so you don’t need the stand-alone files at runtime. 

Pictures display information about the selected disk drive, which you can choose 
using an icon. ViewBmp displays the selected bitmapped image using a PictureBox 
object. Viewlcon shows all the icons on your hard disk using a PictureBox object. 



Chapter 

10 

More on Getting 
Information from the User 


This chapter covers the remaining VX-REXX objects that are used primarily to get 
information from the user. 

SpinButton Object 

A SpinButton object displays a one-line field on the screen that looks very much like 
an EntryField object with a value in it. That field has an up and down arrow on its 
right side. The user can use these arrows to cycle through a series of text values or 
numbers. You can either allow users to enter a custom value not in the predefined 
list or restrict them to just those items in the predefined list. 


Survey-5 

Survey-4, from back in Chapter 8, uses five DropDown ComboBox objects to ask 
users five questions about their computer system. These boxes take up a lot of space 
on the screen. Survey-5 asks these same five questions only using five SpinButton 
objects rather than DropDown ComboBox objects. 

User interface 

Figure 10.1 shows the user interface for Survey-5. Note that the much smaller size of 
the SpinButton objects, which don’t expand while in use, allows the user interface to 
be much smaller than it was in Survey-4. If you required additional information, this 
tighter fit would let you ask more questions in this window. 

Survey-5 uses the SpinButton objects in two different ways. The CPU, screen, and 
case-type questions allow the user to cycle through a limited number of text values. 
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VX-REXX — SURVEY-5 (C:\OS2WXREXX\EXAMPLES\SURVEY-5\SURVEY 
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Figure 10.1 The user interface for Survey-5. It takes up much less screen space than Survey-4. 


This list is defined with the InitialList property on the List tab of the property note¬ 
book. Figure 10.2 shows this for the CPU question. 

The first item in the field is the separator character, used to separate items in the 
field. This must be a character that isn’t used in any of the items, like the comma 
shown in Figure 10.2. A comma allows you to use spaces in each item, so items can 
contain multiple words. It also means that you need to separate items with just a 
comma and not a comma followed by a space. If you do, each item will start with a 
space. 

The CUA (common user access) guidelines suggest that, when the SpinButton ob¬ 
ject works with a series of text objects, clicking on the down arrow should display 
the next string. So clicking on the down arrow takes you to the next item to the right 
as the items are entered in this field, and clicking on the up arrow takes you to the 
next item to the left as the items are entered in this field. Once the end of the list is 
reached in either direction, it begins again at the other end of the list. 

There’s no requirement that the items be listed in alphabetical order, or any other 
order for that matter. I generally try to use a logical sequence of items rather than al¬ 
phabetical order. 
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SpinButton objects can also work with numeric values, as is the case with the 
hard-disk size and memory-size questions in Survey-5. When working with numbers, 
you have two options. First, you can treat the numbers like any other character 
string, and enter it as previously explained. For example, if you wanted someone to 
pick between the numbers 1 to 4, you could enter the InitialList as ,1,2,3,4. The sec¬ 
ond way is to define the smallest number, largest number, and increment, and have 
the SpinButton object cycle through them. The syntax for this is: 


<small TO large BY increment> 


where small is the smallest number to display, large is the largest number to display, 
and increment is the step to take each time an up or down arrow is clicked on. VX- 
REXX increases the number by increment for the up arrow and decreases it by in¬ 
crement for the down arrow. While using the up arrow, once large is reached, it 
recycles to small. While using the down arrow, once small is reached, it recycles to 
large. The angle brackets in the command are required. 

If the Ini tial L is t for a SpinButton is <1 TO 6 BY 2>, then the sequence of values 
while using the up arrow would be 1, 3,5, 6,1, and so on. Initially, the 1 is displayed. 
Clicking on the up arrow increments this by two, to 3 and then 5. Clicking on the up 
arrow again would normally make the value 7, but this exceeds the maximum value, 
so the maximum value of 6 is displayed. Clicking on the up arrow recycles around to 
the minimum value and the sequence begins again. 

When the InitialList contains a list of items, the initial value displayed in the Spin- 
Button object field is the first value in the list. However, when using a range of num¬ 
bers, you have control of what number is initially displayed. That is controlled by 
entering the initial number in the Value field of the Text tab of the property notebook. 



! 




Figure 10.2 The List tab in the property notebook of the 
CPU SpinButton object. Note that the few CPU choices are 
separated by commas. 
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VX-REXX programming 

The programming required by Survey-5 is much less than the programming required 
by Survey-4. Like Survey-4, Survey-5 creates variable names (Boxl-Box5) to store 
the names of the objects used to get information from the user. The allowable values 
are controlled by the InitialList values in the property notebooks, so these don’t have 
to be controlled by the program. Therefore, the five calls to individual subroutines to 
configure each question are eliminated from the Init subroutine and deleted from 
the program. The resulting Init subroutine is: 


Init: 

Return = "Od"x 
window = VRWindow() 

call VRMethod window, "CenterWindow" 
call VRSet window, "Visible", 1 
call VRMethod window, "Activate" 
drop window 
Boxl = "Spin_CPU" 

Box2 = "Spin_Memory" 

Box3 = "Spin_HardDisk" 

Box4 = "Spin_Screen" 

Box5 = "Spin_Case" 
return 


Except for the five variables created at the bottom of the subroutine, these are all 
commands VX-REXX adds by default. 

The display of the report in the Descriptive Text object once the user finishes a 
survey is handled just as it was handled in Survey-4, only there are no DropDown 
ComboBox objects so the program doesn’t reset any DropDown ComboBox objects 
to their default value. 

You might have noticed that the SpinButton objects aren’t reset to a preset value 
after each survey is finished. VX-REXX provides no automatic facility to reset the 
SpinButton object, but you can have the program store some default value and then 
set that value back to the object after each use. The Slider and ValueSet objects, dis¬ 
cussed in the following sections, can be reset in a similar fashion. 


Slider Object 

The Slider object obtains a numeric value from the user, where that numeric value is 
a value from a continuous range of values. Basically, the Slider object functions like 
a sliding volume-control switch on a stereo. 


Survey-6 

Survey-6 is a modified version of Survey-5 that uses a Slider object to obtain the 
amount of memory and hard-disk space from the user. The CPU, case, and video are 
obtained using a SpinButton object because they aren’t numeric values. 

Figure 10.3 shows the user interface for Survey-6. Since the Slider objects look 
very crowded beside the questions, they’re moved below their respective questions. 
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Figure 10.3 The Survey-6 user interface. Two of the SpinButton objects from Survey-5 have been re¬ 
placed with Slider objects. 


The first Slider object reads the amount of memory in one-megabyte increments. 
Since the tick marks correspond to the amount of memory, the Done subroutine can 
simply read the Ticklndex property to find the memory response. 

The second Slider object reads the hard-disk size in one-megabyte increments 
from zero to 1,000. Unlike the first Slider object, this Slider object allows the user to 
move the slider bar to values in between the tick marks. This means the Ticklndex 
property cannot be used to obtain the value because it simply reports the value of 
the closest tick mark. 

Instead, the Percentile property is used. This property reports the percentage of 
the way the slider bar has moved towards the right. This returns a value 0-100 rather 
than a percentage, so the program must convert the percentile value into a scale 
value. The steps for making the conversion are as follows: 

1. Take the percentile value and divide it by 100 to convert it to a raw percentage. 

2. Subtract the lowest value on the scale (the left value) from the highest value on 
the scale (the right value) to obtain the amount of travel for the slider button. 
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3. Multiply the values obtained in steps 1 and 2 together to find the distance trav¬ 
eled by the slider. 

4. Add the value obtained in step 3 to the lowest value on the scale (the left value) 
to obtain the current position of the slider. 

These steps can be simplified in Survey-6. The value of step 1 would be x-rlOO, 
where x is the value returned by the program. Since the lowest value is zero and the 
value of step 2 is 1000, the value of step 3 is (x * 1000)^-100, or x * 10. Since the low¬ 
est value is zero, the value of step 4 remains x * 100, and this is what is used in the 
Done subroutine. This subroutine is as follows: 


Done: 

CPU 

Memory 

HardDisk 

Screen 

Case 


VRGet(Boxl, 
VRGet(Box2, 
VRGet(Box3, 
VRGet(Box4, 
VRGet(Box5, 


"Value") 
"Ticklndex") 
"Percentile") 
"Value") 
"Value") 


10 


Data 

= 

"CPU Type. 

. . " CPU ! I 

Return 

Data 

= Data ! 

! "Memory Amount... 

. ." Memory 

"Meg" !! Return 

Data 

= Data ! 

! "Hard Disk Size.. 

. ." HardDisk "Meg" ! ! Return 

Data 

= Data ! 

1 "Screen Type. 

. ." Screen 

!! Return 

Data 

= Data ! 

! "Case Type. 

. ." Case 



Okay 

return 


VRSet("DT_Results", "Caption", Data) 


Other than the minor changes discussed previously and changing the name of the 
two Slider objects in the Init subroutine, Survey-6 is very much like Survey-5. Figure 
10.4 shows the program in operation. 

ValueSet Object 

The ValueSet object presents the user with a selection of options, only one of which 
can be selected. In that respect, the ValueSet object works much like the RadioBut- 
ton object, except it isn’t necessary to draw multiple objects on the screen and group 
them together. The options displayed in a ValueSet object can be text, a bitmapped 
picture, an icon, an OS/2 color index, or RGB colors. 


Survey-7 

Survey-7 is a modified version of Survey-6 that uses a ValueSet object to obtain the 
case type, screen type, and CPU type and a Slider object to obtain the amount of 
memory and hard-disk space from the user. 

The SpinButton object to determine the CPU type was replaced with a simple 
ValueSet object that has two rows and three columns. Each of the cells is num¬ 
bered, with the top left cell as number one, the next cell in the row as number 
two, and the last cell in the row as number three. At the end of each row, the 
count moves down to the left cell of the next row and increases by one. The Se- 
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13 Survey Versh 

m 6 by Ronny Rich* 
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Please Enter Case Type 
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lienor y Mount 

.8 Heg 
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.Honocfurose 
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. Desktop 





k; 


Done j 

Quit 




Figure 10.4 Survey-6 in operation after one response is received. 


lected property returns the number of the selected cell, which is the usual way to 
determine the selected cell. This could have been performed in the Done subrou¬ 
tine, but to keep that routine at a reasonable length, which cell is clicked is de¬ 
termined by the Click event for each of the three ValueSet objects. The CPU Click 
event subroutine is: 


VS_CPU_Click: 

CPU.l = "8088" 

CPU.2 = "80286" 

CPU.3 = "80386" 

CPU.4 = "80486" 

CPU.5 = "80586" 

CPU.6 = "Other" 

CPUNo = VRGet(Boxl, "Selected") 
return 


The first six rows set up a stem variable containing the possible values, and the last 
row returns the number of the selected cell and uses that as a key to the appropriate 
stem variable. Since the values for the stem variables need to be set only once, this 
portion could easily be moved to the Init subroutine. 
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The screen ValueSet object is handled in a similar fashion, only this time it’s config¬ 
ured to have only a single row of values. The code for this Click subroutine is as follows: 


VS_Screen_Click: 

Screen.1 = "Monochrome" 

Screen.2 = "CGA" 

Screen.3 = "EGA" 

Screen.4 = "VGA" 

Screen.5 = "SVGA" 

ScreenNo = VRGet(Box4, "Selected") 
return 


The case ValueSet object uses icons rather than text. You might notice that the icons 
aren’t shown during design, which can make it a little difficult when you’re working 
with a lot of choices. Otherwise, using icons rather than text doesn’t change the oper¬ 
ation of the ValueSet object. To reinforce the icons, Survey-7 has a small Descriptive 
Text object to the right of the icons. In addition to determining the selection, this Click 
event also displays the selected case time in the box. This subroutine is as follows: 


VS_Case_Click: 

Case.l = "Tower" 

Case.2 = "Notebook" 

Case.3 = "Desktop" 

Case.4 = "Other" 

CaseNo = VRGet(Box5, "Selected") 

Okay = VRSet("DT_Tell", "Caption", Case.CaseNo) 
return 


Since the selection for the ValueSet objects is determined in their respective Click 
events, you can simplify the Done subroutine by referencing this information. The 
Done subroutine follows (the lines changed from Survey-6 are the ones creating the 
CPU, Screen, and Case variables): 


Done: 

CPU = CPU.CPUNo 

Memory = VRGet(Box2, "Ticklndex") 

HardDisk = VRGet(Box3, "Percentile") * 10 

Screen = Screen.ScreenNo 

Case = Case.CaseNo 


Data = 

"CPU Type. 

. ." CPU ! ! 

Return 

Data = Data ! 

! "Memory Amount... 

. ." Memory 

"Meg" !! Return 

Data = Data ! 

! "Hard Disk Size.. 

. ." HardDisk "Meg" ! ! Return 

Data = Data ! 

! "Screen Type. 

. ." Screen 

! ! Return 

Data = Data ! 

! "Case Type. 

. ." Case 



Okay = VRSet("DT_Results", "Caption", Data) 
return 


Figure 10.5 shows Survey-7 in operation after one survey has been completed. 


Viewlcn2 


Viewlcn2 functions as an icon viewer, displaying all the icons on the current hard 
disk, no matter which subdirectory they’re stored in. It has room to display 144 icons 
at a time. If there are fewer than 144 icons, the remaining slots of the ValueSet object 
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Figure 10.5 Survey-8 in operation after one survey is completed. Note that the icons are now displayed. 


are filled with a blank icon bound into the program. If there are more than 144 icons, 
scrolling is supported for the remaining icons. The Forwards button is displayed only 
when it’s possible to scroll forwards, and the Backwards button is displayed only 
when it’s possible to scroll backwards. Viewlcn2 is too large to run on a VGA screen. 

The user interface for Viewlcn2 is made up of a 12 x 12 ValueSet object. Each of 
these cells contains one icon. When the user clicks on an icon, its name and full path 
are displayed in the Descriptive Text object at the bottom of the screen. There are 
also PushButton objects for scrolling and quitting. 

The first problem the program faces is finding all the icons on the hard disk. VX- 
REXX doesn’t have a function for this, so the RexxUtil SysFileTree function is used. 
Of course, this means that those extended REXX functions must be loaded before 
they can be used. All this is handled by the GetAJlIcons subroutine, which the Init 
subroutine calls. The subroutine is as follows: 


GetAllIcons: 

CALL Working SHOW 

CALL RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs' 
CALL SysLoadFuncs 

CALL SysFileTree "*.100", 'Matching.', 'FOS' 

CALL Working HIDE 
return 


Finding all the icons takes a significant amount of time and you don’t want the user 
to think the program has “locked up,” so the subroutine calls the Working subroutine 
with a SHOW argument. 
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When passed a SHOW argument, the Working subroutine displays a separate win¬ 
dow with the phrase “Working” on it, so the user knows the program is doing some¬ 
thing. When the subroutine is passed a HIDE argument, this window is removed. 
Note that the last line of the Working subroutine does this. These techniques are dis¬ 
cussed in Chapter 14; once you’ve finished reading Chapter 14, you might want to re¬ 
turn to this subroutine. 

The next step is to display the icons, which is simple to do with the ValueSet ob¬ 
ject. Unfortunately, it causes a major problem. The ValueSet object is designed to let 
the user pick between objects, not scroll through icons. As a result, it expects that 
the icons won’t change while the program is executing. It allows you to change them, 
but it doesn’t handle the change perfectly. 

When this ValueSet object is filled up, as it would be when your hard disk has more 
than 144 icons, and then a screen is presented with less than 144 icons, as it might 
be when you scroll to the last page of icons, the ValueSet object “remembers” some 
of the icons from the prior screen. Thus, even if they’re supposed to be blank, the 
right column and bottom row display icons. I finally resolved this problem by binding 
in a copy of a blank icon using the VXRez program discussed in the last chapter. Prior 
to assigning the icons to a string variable, all 144 positions in this string variable are 
assigned this bound-in blank icon. Thus, if any of them aren’t assigned an icon to dis¬ 
play, they keep the blank icon assigned to them—which keeps the “remembered” 
icon from being displayed. The operation of this crucial subroutine, called Show- 
Icons, is explained in Figure 10.6. 


VX-Rexx Commands 

Explanation 

Showlcons: 

This subroutine is used to place 
the icons into the ValueSet 
object. 

PROCEDURE EXPOSE FirstShow Matching. LastShow 

Hide all of the variables except 
the FirstShow and LastShow 
variables and the Matching stem 
variable. The Matching stem 
variable contains a list of all the 
icon files on the hard disk. 
FirstShow contains the number 
of the first one to show. 
LastShow is computed by this 
subroutine and used elsewhere 
when the program needs to 
know which cells contain icons 
and which contain a blank cell. 

CALL Working SHOW 

Call the Working subroutine to 
display a message on the screen. 
Since this subroutine takes a 
long time to run, this keeps the 
user from thinking the computer 
has locked up. 


Figure 10.6 The Showlcons subroutine, which assigns the icons to the ValueSet object. Note the use of 
the bound-in blank icon. 
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Kount = Kount + 1 


IconStnng . Kount = Matching. I 



END 


IconStnng. 0 = 144 


Okay = VRMethod ( "VS_1" , "SetAttnbutes' 
"Values", "Iconstring.") 


Increment the counter variable. 


Assign the icon to show to the 
stem variable. This replaces the 
blank bound icon with an actual 
icon to display. If there are not 
enough icons to fill all 144 
available slots, the blank bound 
icon is left in some slots. 


End of the loop. [ 


A count is assigned to the stem 
variable. 


The icons are placed into the 
ValueSet object. 



Finally, when the user clicks on an icon, the program displays the name of that 
icon in a Descriptive Text object. The subroutine that handles this is as follows, with 
line numbers added: 

1. VS_l_Click: 

2. IconNumber = VRGet("VS_1", "Selected") *■ FirstShow - 1 

3. IF IconNumber <- Matching.0 THEN IconName = Matching.IconNumber 
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4. ELSE IconName = "No Icon" 

5. Okay = VRSet("DT_Name", "Caption", IconName) 

6. return 

The RexxUtil SysFileTree function assigns all the icons to be displayed to a stem 
variable and stores them in the Matching stem variable. Line 2 computes the icon 
number for the icon the user clicked on. Line 3 checks to see if that matches an icon 
and, if it does, it displays the name of the icon in a variable. If the number exceeds 
the number of available icons, then the user clicked on a blank cell and an appropri¬ 
ate response is stored to the variable. Line 5 displays that variable as the caption of 
a Descriptive Text object. Figure 10.7 shows Viewlcn2 in operation. 

Summary 

The SpinButton, Slider, and ValueSet objects allow you to obtain information from 
the user. Survey-5 improves on Survey-4 by asking questions using SpinButton ob¬ 
jects, which take up less space than DropDown ComboBox objects. Survey-6 modi¬ 
fies Survey-5 to use Slider objects in order to get the numeric information. Survey-7 
modifies Survey-6 to use ValueSet objects in order to get the nonnumeric informa¬ 
tion. Viewlcn2 displays all the icons on the current hard disk, 144 at a time. 



Icon Viewer by Ronny Richardson 




F:\tempicon\FACE1.ICO 


Figure 10.7 Viewlcn2 in operation, displaying 144 icons. 





































Chapter 

11 

Other Objects 


This chapter will round out coverage of VX-REXX objects. 

Notebook Object 

The Notebook object presents a familiar VX-REXX OS/2 property notebook with 
which the user can change values. This property notebook is under the program¬ 
mer’s complete control. Each tab and setting must be preprogrammed. 


Notebook 

The Notebook program is a demonstration program that puts two buttons on the 
screen. One button brings up its property notebook, where the user can change the 
caption, size, and colors of the button. Changes made in the property notebook are 
immediately reflected in the button. The other button exits the program. 

A notebook is usually designed to pop up when needed and, once the necessary 
changes are made, it again goes into hiding. In a VX-REXX program you put the 
object to pop up into a new window. VX-REXX can then display that window when 
it’s needed and hide it otherwise. Using multiple windows is discussed in detail in 
Chapter 14. For now, you can use the Window dialog box (press F8) to add new 
windows. 


Adding the Notebook object 

You use the New option from the window dialog box menu to add a window, and then 
change its name under the General tab of its property notebook. Let’s call the win¬ 
dow containing the Notebook object Notebook. Once you’re finished working in a 
window, you can use the Close option from the menu so it doesn’t continue to clut¬ 
ter up the screen. 

Once the new window is ready, you can add a Notebook object to it (see Figure 
11.1). Note that the resulting property notebook initially has no tabs and no items in 
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inclaws — notebooi 


Window 


Windowl 


ftjVX-REXK~ — N0TEB0QK~"(C^\Q$2WXREXX\£H AMPL£3UiDTEB00K\M0TE 

Project loots Windows Run Options Help _ 

j Object: ‘Notebook’ [EditWlndow] _ 


j pj Property Notebook Example by Ronny Richardson 


j j Click Here To See Notebook 


Figure 11.1 The first step in designing a property notebook is to place a Notebook object in a separate 
window, which allows the object to pop up on demand and close when no longer needed. 


it. Since these are under the programmer’s control, each tab and item has to be man¬ 
ually added. Each tab will go into a separate window. This window is created and ob¬ 
jects are added to it without any consideration for the Notebook object. Once the 
tabs are ready, the Notebook object is configured to treat each window as a tab. 
However, they’re compiled together and displayed as a finished property notebook 
only when the program is running. 

The caption page of the Notebook object 

Next you need to create a new window called ButtonText. This page will contain an En- 
tryField object to receive the new caption for the button, shown in Figure 11.2. As a 
new caption is entered in the EntryField object, the caption for the original PushButton 
object (PB_1) needs to change. This is handled by the Change event, as shown here: 

EF_l_Change: 

Text = VRGet("EF_1", "Value") 

Okay = VRSet("PB_1", "Caption", Text) 
return 

This subroutine simply reads the new caption and inserts it in the PushButton ob¬ 
ject. Since this subroutine is activated each time the text in the EntryField object 
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is changed, as the user types a new caption in the EntryField object the PushBut- 
ton object caption is continually updated. When you run the Notebook program, 
you want to make sure that the property notebook isn’t blocking the main part of 
the program. 

The color page of the Notebook object 

The Colors window, shown in Figure 11.3, is used to construct the next page of the 
property notebook. Two DropDown ComboBox objects are used, one for the fore¬ 
ground color and one for the background color. All 16 possible colors are pro¬ 
grammed into the InitialList, along with the default, so the user can change to the 
default color. 

The Change event needs to read the selected color from the DropDown Com¬ 
boBox object and make that the color for the PushButton object. The foreground 
color subroutine is: 


DDCB_Foreground_Change: 

ForeColor = VRGet("DDCB_ForeGround", "Value") 
Okay = VRSet("PB_1", "ForeColor", ForeColor) 
return 


The background color subroutine works in a similar fashion. 
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Figure 11.2 Constructing a tab to change the PushButton caption. 
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Figure 11.3 Constructing a tab to control the foreground and background colors of the PushButton object. 


The size page of the Notebook object 

The Size window, shown in Figure 11.4, is used to construct the last page of the 
property notebook. Two EntryField objects are used, one for the height and another 
for the width. A CheckBox object gives the user the option of “autosizing” the Push- 
Button object. This tab of the property notebook is the most complex. 

When this page is activated, the height and width EntryField objects need to be 
seeded with the existing sizes of the PushButton object. This is handled by the Cre¬ 
ate subroutine, with the following code: 

Size_Create: 

Height = VRGet("PB_1", "Height") 

Width = VRGet("PB_1", "Width") 

CALL SetHeightWidth 
return 

The SetHeightWidth subroutine is: 

SetHeightWidth: 

Okay = VRSet("EF_Height", "Value", Height) 

Okay = VRSet("EF_Width", "Value", Width) 
return 


This subroutine simply takes the values stored in the Height and Width variables and 
places them into their respective EntryField objects. Since Height and Width are 
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used as variable names, you must place them in quotation marks when using them as 
property names. 

The Autosize CheekBox object is initially not checked. The Change event for the 
CheckBox object is as follows: 


CB_Size_Click: 

Autosize = VRGet("CB_Size", "Set") 

Okay = VRSet("PB_1", "AutoSize", Autosize) 
IF Autosize = 1 THEN 
DO 

Height = VRGet("PB_1", "Height") 
Width = VRGet("PB_1", "Width") 

CALL SetHeightWidth 

END 

return 


This subroutine reads the CheckBox object and stores its value to the Autosize prop¬ 
erty of the PushButton object. It also creates an Autosize variable that contains a 1 
if autosizing is turned on. The EntryField objects will use this variable to decide if 
the height or width can be changed. The Change event for the height EntryField ob¬ 
ject is: 


EF_Height_Change: 

Autosize = VRGet("CB_Size", "Set") 
IF Autosize = 1 THEN 
DO 
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Figure 11.4 Constructing a tab to control the size of the PushButton object. 




':: . : 






































































136 


Introductory VX-REXX Topics 


Height = VRGet("PB_1", "Height") 

Okay = VRSet("EF_Height", "Value", Height) 

CALL SetHeightWidth 

RETURN 

END 

Height = VRGet("EF_Height", "Value") 

Okay = VRSet("PB_1", "Height", Height) 
return 


The subroutine first checks to see if autosizing is turned on. If it is, the current 
height is read from the PushButton object and placed back into the EntryField ob¬ 
ject. Thus, each time a number is changed with autosizing turned on, it’s returned to 
the original value. When autosizing is turned off, the new number is read from the 
EntryField object and used as the height of the PushButton object. Since this hap¬ 
pens each time the number is changed, the height changes dynamically as the user 
enters a new number. The width operates in a similar fashion. 


Pulling it ail together 

Once each tab is ready, all that remains to do is to tell the Notebook object where to 
find each page. Do this on the property notebook’s Pages tab using the InitialPage- 
List setting. The first character is the page divider (I’ve used a semicolon). The name 
of each window is entered after that just as the window is named in VX-REXX. To en¬ 
ter a name for that tab for display, follow the name of the window with a plus sign and 
the name to use for the tab. All this is shown in Figure 11.5. While not all of it is vis¬ 
ible, the full InitialPageList string is ;ButtonText+Caption;Colors+Colors;Size+Size. 

Figure 11.6 shows the program in operation. Note that the caption of the Push- 
Button object has been changed, and autosizing is turned on so the PushButton ob¬ 
ject is much smaller than normal. 


Container Object 

The Container object creates an internal database with fields and records. Associ¬ 
ated methods allow you to manipulate the fields and records. The Container object 
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Figure 11.5 Using the Notebook 
object’s property notebook to pull 
the individual windows together 
under the Notebook object. 
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Figure 11.6 The final version of the 
Notebook program, in operation. 
The PushButton object’s caption 
and size have been changed. 


will display the database in a variety of formats, and let you control how the infor¬ 
mation is displayed on the screen. 


Contain 

The Contain program locates all the icons on the drive from which the program is 
started, starting with the current subdirectory and including all the subdirectories 
that branch off of it. It then constructs a database containing the icon, its name, sub¬ 
directory, size, creation date, and creation time. PushButton objects allow you to 
switch between the seven views supported by the Container object. 


Getting the data 

The Init subroutine first calls the GetAllIcons subroutine. This subroutine uses the 
RexxUtil SysFileTree external function to locate all the *.ICO files on the hard disk 
and store their name and full path in the Matching stem variable. As written, this 
program offers no error-handling if the program doesn’t find any icons on the disk. 
The Init subroutine is as follows: 


GetAllIcons: 

CALL Working SHOW 

CALL RxFuncAdd 'SysLoadFuncs', 'RexxUtil', 'SysLoadFuncs' 
CALL SysLoadFuncs 

CALL SysFileTree "*.ICO", 'Matching.', 'FOS' 

CALL Working HIDE 
return 
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This subroutine, as well as the subroutine that constructs the database, both take a 
lot of time. To keep the user from thinking that the program has locked up, it dis¬ 
plays a separate window with the message “Working” while the program is running. 
The use of additional windows is discussed in detail in Chapter 14. The Working sub¬ 
routine either displays or hides this secondary window, depending on the argument 
passed to it. The Working subroutine is: 


Working: 

PROCEDURE 
WhatToDo = Arg(l) 

IF WhatToDo = "SHOW" THEN Okay = VRLoadSecondary("Working") 
ELSE Okay = VRDestroy("Working") 
return 


Working with the database 

The Init subroutine next constructs the database fields inside the Container object. 
The code that does this is: 


Fields.!Icon 
Fields.!Name 
Fields.!Size 
Fields.!Date 
Fields.!Time 
Fields.!Dir 


VRMethod("CN_1", 
VRMethod("CN_1", 
VRMethod("CN_1", 
VRMethod("CN_1", 
VRMethod("CN_1", 
VRMethod("CN_1", 


"AddField", 
"AddField", 
"AddField", 
"AddField", 
"AddField", 
"AddField", 


"Icon", "Icon" ) 

"String", "Name" ) 
"ULong", "Size" ) 

"Date", "Date") 

"Time", "Time") 

"String", "Subdirectory") 


Six database fields are created and stored to the Fields stem variable. They are: 


Icon. This is where the file icon is stored. While the icons on a disk naturally have 
their own icons, many files don’t. The following generic icons are supported: 

■ Application 

■ Information 

■ Question 

■ Error 

■ Warning 

■ Illegal 

■ File 

® Multiple files 

■ Folder 

■ Program 

Although too late to be included in this example, version 2.0a adds support for field 
names, so the program no longer needs to store field handles to a variable. Of course, 
this approach still works. 
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IName. The name of the icon file is stored here. 

!Size. The size of the icon file is stored here. 

SDate. The creation date of the icon file is stored here. 

!Time. The creation time of the icon file is stored here. 

!Dir. The name of the subdirectory containing the icon file is stored here. 

Next, the Init subroutine calls the StoreToContainer subroutine to place all the 
data from the Matching stem variable into the database. The operation of this crucial 
subroutine is explained in Figure 11.7. 



Function 

StoreToContainer : 

Name of the subroutine. 

CALL Working SHOW 

Calling the Working subroutine 
to show a pop-up window to let 
the user know the program is 
doing something. 

DO 1=1 TO Matching.0 

Loop through all the filenames. 

IconName = VRDir(Matching.I, "N") 

Store the filename to a variable. 

IconSize = VRDir(Matching.I, "S") 

Store the size to a variable. 

TempDate = VRDir(Matching.I, "D") 

Store the date to a variable. 

PARSE VALUE TempDate WITH Month "/" Day 
"/" Year 

Since the date is not stored in 
the proper format, parse it into 
its component parts. 

IconDate = "19" Year || Month | Day 

Reassemble the component parts 
into the proper format. 

TempTime = VRDir(Matching.I, "T") 

Store the time to a variable. 

PARSE VALUE TempTime WITH Hour ":" 

Minute ":" Second 

Since the time is not stored in 
the proper format, parse it into 
its component parts. 

IconTime = Hour || Minute || Second 

Reassemble the component parts 
into the proper format. 

Directory = VRParseFileName(Matching.I,"P" ) 

Store the subdirectory to a vari¬ 
able. 

IF Directory = "" THEN Directory = "Root" 

If that variable is empty, then it 
was in the root directory (the 
lone \ is not returned by the 
function), so store “Root” to the 
variable. 

Record = VRMethod ( "CN_1 " , "AddRecord", , , 

IconName, Matching.I ) 

Create a new record. 


Figure 11.7 The StoreToContainer subroutine, which places data into the Container object database. 
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Function 

Okay 

= VRMethod ( "CN_1" , " SetFieldData" , 

Store the components created 


Record, Fields .! Icon, Matching.I) 

above to their appropriate field 

Okay 

= VRMethod ( "CN_1 #/ , "SetFieldData", 
Record, Fields.!Name, IconName) 

in this new record. 

Okay 

= VRMethod("CN_1", "SetFieldData", 
Record, Fields .! Size, IconSize) 


Okay 

= VRMethod ( "CN_1 " , "SetFieldData", 
Record, Fields .! Date, IconDate) 


Okay 

= VRMethod ( "CN_1", "SetFieldData", 
Record, Fields .! Time, IconTime) 


Okay 

= VRMethod ( "CN_1", "SetFieldData", 
Record, Fields.!Dir, Directory) 


END 


End of the DO 1 = 1 TO 
Matching.0 loop. 

CALL Working HIDE 

Call the Working subroutine to 
hide the “Working” window. 

return 


Exit the subroutine. 


Figure 11.7 Continued. 


Manipulating the database 

The Container object offers seven different views of the data: 

Detail. This is shown in Figure 11.8. 
icons. This is shown in Figure 11.9. 

Icon Tree. This is shown in Figure 11.10. 

Name. This is shown in Figure 11.11. 

Name Tree. This is shown in Figure 11.12. 

Text. This is shown in Figure 11.13. 

Text Tree. This is shown in Figure 11.14. 

Switching between the views requires a single line to change the View Property 
of the Container object. The subroutine that switches to the Name Tree view is as 
follows: 


PB_NameTree_Click: 

Okay = VRSet("CN_1", 
return 


"View", "NameTree") 
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Figure 11.8 The Contain program in Detail view. 
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Figure 11.9 The Contain program in Icon view. 
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Figure 11.11 The Contain program in Name view. 
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Figure 11.12 The Contain program in Name Tree view. 
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Figure 11.13 The Contain program in Text view. 
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DragDrop 

If you want to learn more about the Container object, the DragDrop sample program 
that comes with VX-REXX is an excellent learning tool. It shows two Container 
objects on the screen with four information icons in each Container object. As these 
icons are dragged from one Container object and dropped into the other, it displays 
information about the icons on the screen. 

More detail on DragDrop is provided in Chapter 13. If you want to learn more 
about Container objects and DragDrop, you can find the DragDrop program in the 
VXREXXVSAMPLES subdirectory after installing VX-REXX. 

File Browser 

File Browser displays the files and subdirectories on your hard disk and lets you click 
on different icons to move around the hard disk, viewing the contents of different 
subdirectories. Since it uses a Container object, all of the views supported by the 
Container object are supported. It doesn’t let you view the contents of individual 
files as the name might imply. 

More detail on File Browser is provided in Chapter 13. If you’re interested in learn¬ 
ing more about the Container object and File Browser, look at the File Browser pro¬ 
gram in the VXREXX\SAMPLES subdirectory after installing VX-REXX. 

DDEClient Object 

VX-REXX has a DDEClient object for making your VX-REXX a client of a DDE ex¬ 
change with another program. This is an advanced topic, so it’s covered in Chapter 20. 
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Timer Object 

The Timer object generates a Trigger event at specific intervals. This event can then 
be used to accomplish tasks that need to be repeated, such as flashing a message or 
beeping the speaker. However, don’t depend on this interval for keeping time be¬ 
cause some interactions with OS/2 will keep the Trigger event from being generated 
at the appropriate time and VX-REXX will queue only one Trigger event. 

Additionally, processing-intensive actions within VX-REXX itself will also prevent 
the Trigger event from being regularly generated. I tried using a Timer object to 
cause the Working window in the Contain program to blink by alternating foreground 
colors, but the intensive nature of building the database prevented Trigger events 
from being generated. 


Beeper 

Beeper is a demonstration program that shows how to use Timer object Trigger 
events to automatically schedule actions. Once the user presses on the button to ac¬ 
tivate the beeper, the Trigger event beeps the speaker and turns a Descriptive Text 
object containing the message “Beep” on and off. A Slider object for altering the de¬ 
lay between Trigger events and a Descriptive Text object containing a title for the 
Slider object are also made visible while the beeper is on. 

Figure 11.15 shows the user interface for the Beeper program. While the dimer object 
is visible in this figure, it’s never visible while the program is running because its Visible 
property is turned off. The code for the Click event of the start PushButton object is: 


PB_Start_Click: 

Okay = VRSet("TM_1", 
Okay = VRSet("SL_1", 
Okay = VRSet("SL_1", 
Okay = VRSet("DT_2", 
return 


"Enabled", 
"Visible", 
"Enabled", 
"Visible", 


1 ) 

1 ) 

1 ) 

1 ) 



Figure 11.15 The user interface for Beeper. Note that the timer and other 
objects are visible. 
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The first line enables the Timer object. The second line makes the Slider object for 
altering the delay between Trigger events visible, while the third line enables it. The 
fourth line makes the Descriptive Text object that describes the Slider object visible. 
The Click event of the Stop PushButton object simply reverses these actions. Its 
code is: 


PB_Stop_Click: 

Okay = VRSet("TM_1", "Enabled", 0) 
Okay = VRSet("DT_Beep", "Visible", 0) 
Okay = VRSet("SL_1", "Visible", 0) 
Okay = VRSet("SL_1", "Enabled", 0) 
Okay = VRSet("DT_2", "Visible", 0) 
return 


The second line to hide the DT_Beep Descriptive Text object that displays the large 
“Beep” is necessary because this object is made alternately visible and invisible by 
the Timer object Trigger event. But you can’t be sure that it will be invisible when 
this subroutine is executed, so it needs to go ahead and hide the object. 

The Trigger event of the Timer object is activated repeatedly. The frequency of ac¬ 
tivation is controlled by the Delay property of the Timer object. The Trigger event of 
the Timer object is as follows: 


TM_l_Trigger: 

CALL Beep 500, 500 
IF Seen = "NO" THEN 
DO 

Seen = "YES" 

Okay = VRSet("DT_Beep", "Visible", 1) 

END 

ELSE 

DO 

Seen = "NO" 

Okay = VRSet("DT_Beep", "Visible", 0) 

END 

return 


The event begins by beeping the speaker. After that, if the DT_Beep Descriptive 
Text object is invisible it makes it visible, and if it’s visible it makes it invisible. If it’s 
visible when the Timer object is disabled, the routine that disables the Timer object 
also hides the DT_Beep object. 

Figure 11.16 shows the program before the beeper has been activated. Note that 
the Slider object and its description inside the Descriptive Text object, as well as the 
Timer object and Beep Descriptive Text object, are invisible. Figure 11.17 shows 
Beeper in the process of beeping. While the Slider object and Descriptive Text ob¬ 
jects are now visible, the Timer object is still hidden. 


Summary 

This chapter shows how to construct a property notebook that lets the user control 
the attributes of VX-REXX objects. When using the Notebook object, it’s important 
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Figure 11.16 Beeper running before the Timer object is ac¬ 
tivated. Note that the Timer, Slider, and Descriptive Text 
objects are invisible. 



Figure 11.17 Beeper running after the Timer object is acti¬ 
vated. The Slider and Descriptive Text objects are visible, 
but the timer object is still invisible. 

to remember that you must program every attribute the user can change into the 
property notebook. 

This chapter also shows how to use a Container object to construct a database of 
filenames and attributes, and how to use the Timer object to generate Trigger events 
at regular intervals. 

The Notebook program uses a Notebook object to display a property notebook for 
a PushButton object. The user can use this property notebook to change the Push- 
Button object’s caption, size, and color. The Contain program uses the Container ob¬ 
ject to display all the icons on the hard disk in a variety of formats. Beeper uses a 
Timer object to beep the speaker and flash a message repeatedly. 







Chapter 

12 

VX-REXX Functions 


VX-REXX includes a number of its own functions to supplement those included 
with REXX and RexxUtil. In fact, these functions are complete enough that you’ll 
rarely have to load the RexxUtil functions. These VX-REXX functions fall into two 
broad categories: those designed to work with VX-REXX objects and those de¬ 
signed to work with the OS/2 environment. This chapter will cover the functions 
that work with VX-REXX objects and then those that work with the OS/2 envi¬ 
ronment. 

While this chapter gives the syntax for each function, the purpose of this book is 
not to replace your manual, so I haven’t tried to cover every nuance of every func¬ 
tion. This chapter will tell you what each function does, what input it needs, and gen¬ 
erally how to use it. This will, in most cases, be enough information to use these 
functions in your programs. However, when you need very specific information, con¬ 
sult your manual or the VX-REXX online documentation. 


Using Functions in Your Code 

One of the functions I’ll discuss later is VRChDir, which changes to a new subdirec¬ 
tory. Its single input is the new subdirectory to change to. There are two ways to use 
a function in your code: as a function or as a subroutine. To use VRChDir as a func¬ 
tion, the syntax would be: 


Okay = VRChDir( subdirectory) 


where Okay is the name of the variable to store the results of the function to. When 
a function doesn’t need to return any information, as is the case with VRChDir, it typ¬ 
ically returns a 1 if it was successful and a 0 if it failed. When used in this fashion, an 
open parenthesis must immediately follow the function name. Inside the parenthe- 
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ses, the arguments being passed to the function are separated by commas. Spacing 
inside the parentheses is ignored. 

The second way to use a function is to call it as a subroutine. When used in this 
fashion, the syntax is: 

CALL VRChDir subdirectory 

There is a space between the function name and the first argument. If there are ad¬ 
ditional arguments, they’re separated from the first by a comma. Spacing is ignored. 
Since there’s no variable to return information to when a function is called as a sub¬ 
routine, that information is automatically stored in the variable Result. 

In this book, I’ll generally use the first method for a function. However, any of the 
functions can be used in either manner. 

Functions That Work with VX-REXX Objects 

Like REXX, VX-REXX programs are very malleable. When you use VX-REXX 
functions, a program can change most of the properties of its objects while it’s 
running. In fact, you can change even the code associated with its objects at run¬ 
time, as you saw with the Todo program back in Chapter 6. The VX-REXX func¬ 
tions for working with objects while a program is running are discussed in this 
section. 

Does an object exist? (VRIsVaSidObject) 

The VRIsValidObject function tests to see if the specified VX-REXX object or Pre¬ 
sentation Manager window handle exists. It returns a 1 if it exists and a 0 if it doesn’t 
exist. The syntax is: 


Okay = VRIsValidObject( object) 


where object is the name of the VX-REXX object or Presentation Manager window 
handle to test. 

Getting an error message (VRError) 

Unlike OS/2 commands, VX-REXX functions can’t depend on being able to display an 
error message on the screen. When an error occurs with a function, that error mes¬ 
sage is stored in memory. The VRError function allows you to read the last error 
message. Its syntax is: 


LastError = VRError() 

Note that this function doesn’t use any arguments. You might use this function in an 
error-handling routine to tell the user what happened. It’s also useful in debugging a 
program. 
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Getting information from objects (VRGet) 

VRGet polls VX-REXX objects and returns information about them. VRGet and 
VRSet (discussed later) will likely be the two most common VX-REXX functions in 
your programs. The syntax for VRGet is: 


Property = VRGet( object , property) 


where object is the VX-REXX object to retrieve information from and property is the 
object property to retrieve. 

Each VX-REXX object has a set of properties associated with it. For example, the 
properties associated with the Descriptive Text object are as follows: AutoSize, 
BackColor, Caption, ClassName, Enabled, FirstChild, Font, ForeColor, Height, Help- 
Tag, HelpText, HintText, HWnd, Justification, Left, Name, Painting, Parent, Self, Sib¬ 
ling, SiblingOrder, Tablndex, Top, UserData, VertJustification, Visible, Width, and 
WordBreak. You can query each of these properties and return its value by using the 
VRGet function. As you’ll see, you can also change the value of most of these prop¬ 
erties with the VRSet function. 

Getting information on the last event (VRInfo) 

The VRInfo function returns information about the last event returned from the 
VREvent function. Its syntax is: 


Eventlnfo = VRInfo(type) 


where type is either E to get the name of the event, or 0 to get the VX-REXX inter¬ 
nal name of the event. 

Getting the next event (VREvent) 

You can use the VREvent function to return the event string for the next event to be 
processed in a program. Its syntax is: 


NextEvent = VREvent([N/W]) 


where N/W specifies if VREvent should wait (W) or not wait (N) if no event is pend¬ 
ing. If no event is pending and the N option is used, NOP is returned. 

Getting the VX-REXX version number (VRVersion) 

The VRVersion function returns the version number and date of a VX-REXX .DLL 
(dynamic link library) file. Its syntax is: 


Version = VRVersion( dllname) 


where dllname is the name of the library to check. 
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Getting the window name (VRWindow) 

You can use the VRWindow function to get the internal name of the primary window 
for the current program. If you specify a window name, that window is made the cur¬ 
rent window. Its syntax is: 


Window = VRWindow( [newwindow] ) 


where newwindow is the optional window to make current. 

Getting the Window Path (VRWindowPath) 

The VRWindow function returns the path of the primary windows for the current 
program. Its syntax is: 


WindowPath = VRWindowPath() 

Initializing the VX-REXX programming environment (VRInit) 

The VRInit function initializes the VX-REXX programming environment. It must be 
the first function called and is handled automatically by VX-REXX when you create 
a program. Its syntax is: 


Okay = VRInit() 


Invoking the object method (VRMethod) 

The VRMethod function invokes the method of an object. Its syntax is: 


Method = VRMethod( object, method, [ arguments ]) 


where object is the name of the object whose method is to be invoked, method is the 
name of the method to invoke, and arguments are any arguments required by the 
particular method. These can be omitted if they aren’t required. 

Different objects have different methods that return different information, so the 
returned value of the VRMethod function is very specific to the method on which it’s 
used. If the method doesn’t return a value, a 1 is returned if the method was suc¬ 
cessfully invoked; otherwise, a 0 is returned. 


Loading secondary window description from a file (VRLoadSecondary) 

The VRLoadSecondary function loads the description of a secondary window from a 
file. Its syntax is: 


Window = VRLoadSecondary( window) 


where window is the name of the secondary window to load. This information 
must be contained in the same file as the current primary window. If the function 
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is successful, it returns the internal name of the window; otherwise, it returns a 
null string. 

Loading window description from a file (VRLoad) 

The VRLoad function loads the description of a window from a file. Its syntax is: 


Window = VRLoad(parent, path, [window]) 


where parent is the name or handle of the object to be the parent of the window 
being loaded (using a null string causes the OS/2 desktop to be the parent), path 
is the name and associated path of the file that contains the description of the 
window, and window is the optional name of the window to load. If the operation 
is successful, it returns the internal name of the window; otherwise, it returns a 
null string. 

Picking a filename (VRFileDialog) 

The VRFileDialog function offers a convenient way for the user to pick a filename 
when one is required. The function displays a standard OS/2 dialog box. Once the 
user selects a file, its fully qualified name is returned by the function. The syntax 
is: 


FileName = VRFileDialog( object, title, type, [initialpath], 
[initialtype], ["Drives.x"], ["Types.x" ] 


where: 

* Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop is disabled. 

■ Title is the title of the dialog box. 

b Type is the type of dialog box to use. The two types are 0 for open (a file) and S 
for save. 

■ Initialpath is the initial path to use for displaying files. You can specify a file mask 
to control the filenames that show in the dialog box. 

® Initialtype is the initial type of file to initially show in the dialog box. The default 
is to show all files. 

■ Drives is a stem variable that controls the drives that are displayed in the dialog 
box. Drives.0 must contain the number of drives, with Drives. 1 containing the first 
drive, Drives.2 the second, and so on. 

■ Types is a stem variable that controls the type of files displayed in the drop-down 
list. Types.0 must contain the number of file types, Types. 1 the first type, Types.2 
the second type, and so on. 

Using the VRFileDialog function was explained in detail back in Chapter 6. 
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Putting information into objects (VRSet) 

The VRGet function returns the values of object properties at runtime. You can 
change the values of these same properties to new values using the VRSet function. 
Its syntax is: 


Okay = VRSet ( object, property, value, [property2, value2] , [...]) 

where object is the object to have a property value modified, property is the prop¬ 
erty to modify, and value is the new value to give that property. The VRSet function 
allows you to alter the operation of a program while it’s running. 


Redirecting standard I/O (VRRedirectStdIO) 

The VRRedirectStdIO function redirects the standard I/O to the VX-REXX console 
window. Its syntax is: 


Okay = VRRedirectStdIO("On", [logfile]) 
Okay = VRRedirectStdIO("Off", [message]) 


where “On” or “Off’ determines if the standard I/O stream is redirected, logfile is the 
name of a log file to get a copy of messages, and message is a message to be dis¬ 
played before the console is closed. Most users won’t have to use this function as it’s 
handled automatically by VX-REXX. It returns a 1 if redirection was successful, a 0 
otherwise. 


Setting VX-REXX runtime options 

VX-REXX version 1.01 and earlier didn’t generate a syntax error when the VRGet, 
VRSet, and VRMethod functions were passed an invalid object name. VX-REXX ver¬ 
sion 2 and later does. This function allows you to configure VX-REXX to behave like 
version 1.01. The syntax is: 


Okay = VROptions ( option) 


where option can be ‘Syntax’ (the default) to cause VX-REXX to generate syntax er¬ 
rors for invalid object names, or ‘NoSyntax’ to cause VX-REXX to behave like version 
1.01 and ignore invalid object handles. 


Showing error message to the user (VRMessage) 

The VRMessage function is a handy way to display an error message to the user and 
provide several alternatives for resolving the problem. Its syntax is: 


Button = VRMessage( object, message, [title], [icon], 
["Button. x" ], [default], [escape]) 
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where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop is disabled. 

■ Message is the message to be displayed in the dialog box. 

■ Title is the title of the dialog box. 

■ Icon is a single character indicating the type of icon to display in the box. The pos¬ 
sible values are: E (an error icon), I (an informational icon), N (no icon), Q (a 
query icon), and W (a warning icon). 

■ Button is the stem variable that contains the button text. Button.O must contain the 
button count, Button. 1 the text for the first button, Button.2 the text for the sec¬ 
ond button, and so on. If no buttons are specified, a single OK button is displayed. 

■ Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

■ Escape is the button to assume was pressed if the user presses Escape. 

This function returns the number of the button that was pressed. If Escape is 
pressed, it returns a zero. The VRMessage function is explained in more detail in 
Chapter 6. 

Showing a message to the user and getting a long response (VRPrompt) 

The VRPrompt function displays a prompt to the user in a dialog box and then ob¬ 
tains a lengthy response from users. For example, it might ask for names or ad¬ 
dresses. It also has the option of displaying buttons and returning the button that 
was pushed. Its syntax is: 


Button = VRPrompt( object, prompt, contents, [title], 
["Buttons.x"]/ [default], [escape]) 


where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled while the dialog box exists. If a null string is specified, the 
entire OS/2 desktop is disabled. 

■ Prompt is the message to display for the user. 

■ Contents is the name of the variable to receive the information the user types into 
the dialog box. This is required since the function itself returns the number of the 
button that is pushed. 

■ Title is the title of the dialog box. 

■ Button is the stem variable that contains the button text. Button.O must contain the 
button count, Button. 1 the text for the first button, Button.2 the text for the sec¬ 
ond button, and so on. If no buttons are specified, a single OK button is displayed. 
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a Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

H Escape is the button to assume was pressed if the user presses Escape. 

The VRPrompt function is explained in detail in Chapter 6. 

Showing multiline error message to the user with a stem variable (VRMessageStem) 

The VRMessageStem function works almost exactly like the VRMessage function 
only its message is stored in a stem variable, so multiline messages can be displayed. 
Its syntax is as follows: 


Button = VRMessageStem {object, "Message", [title], [icon], 
["Button."], [default], [escape]) 


where: 

■ Object is the name of the window to which the dialog box is modal. The named 
window is then disabled when the dialog box exists. If a null string is specified, the 
entire OS/2 desktop is disabled. 

■ Message is the name of the stem variable that contains the message. Message.0 
must contain the count of the lines, Messaged the first line of the message, Mes¬ 
saged the second line, and so on. 

■ Title is the title of the dialog box. 

■ Icon is a single character indicating the type of icon to display in the box. The pos¬ 
sible values are: E (an error icon), I (an informational icon), N (no icon), Q (a 
query icon), and W (a warning icon). 

■ Button is the stem variable that contains the button text. Button.0 must contain the 
button count, Button. 1 the text for the first button, Button.2 the text for the second 
button, and so on. If no buttons are specified, a single OK button is displayed. 

■ Default is the number of the default button to assume was pressed if the user 
presses the Enter key. This button is also highlighted. 

■ Escape is the button to assume was pressed if the user presses Escape. 

This function returns the number of the button that was pressed. If Escape is 
pressed, it returns a zero. 

Terminating the VX-REXX programming environment (VRFini) 

The VRFini function terminates the VX-REXX programming environment. You don’t 
need to worry about this function because it’s automatically added to an application 
by VX-REXX. Its syntax is: 

Okay = VRFini () 


It returns a 1 if the termination was successful and a 0 otherwise. 
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Functions That Work with the OS/2 Environment 

You don’t need any of the functions that follow! These functions duplicate abilities 
that already exist in either REXX, RexxUtil, or OS/2 commands, so you can safely 
avoid all of them. In fact, when I first started working with VX-REXX I did just that. 
I had written several VX-REXX programs using REXX functions and OS/2 commands 
before I realized that these functions were available. 

While you can get along without them, they’re nice to know and use. Some of 
them, like the renaming function, are more powerful than the REXX or OS/2 equiva¬ 
lents. While most are no more powerful than their REXX or OS/2 counterparts, it’s 
nice to keep everything in one language and not worry about dropping to OS/2 to is¬ 
sue a command or loading the external RexxUtil functions. Also, if you’re distribut¬ 
ing programs to other users, you can’t be sure that the OS/2 commands and RexxUtil 
functions have even been installed. 


Changing a file type (VRSetFileType) 

The VRSetFileType changes or sets a file type. Its syntax is: 


Okay = VRSetFileType( file, type) 


where file is the name of the file (drive and path can be used, but wildcards aren’t 
supported) and type is the OS/2 file type. The function returns a 1 if it’s successful 
and a 0 if it fails. 


Changing drives (VRChDrive) 

The VRChDrive function changes the current drive. Its syntax is: 


Okay = VRChDrive {newdrive) 


where newdrive is the new drive to change to. A colon isn’t required after the drive 
letter. The function returns the drive that was in use prior to calling the function, fol¬ 
lowed by a colon. 

Changing file attributes (VRChAttr) 

The VRChAttr function changes the archive, hidden, read-only, and system attrib¬ 
utes of a file. This function duplicates the OS/2 Attrib command. Its syntax is: 

Okay = VRChAttr( file, [on], [off]) 

where file is the file specification to change (wildcards are supported), on are the at¬ 
tributes to turn on, and off are the attributes to turn off. You need to specify only the 
first letter of attributes, and capitalization is ignored. The function returns a 1 if it’s 
successful and a 0 if it fails. 
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Changing file dates and times (VRFileDate) 

The VRFileDate function changes the date and/or time associated with a file. Its syn¬ 
tax is: 

Okay = VRFileDate( file, [newdate], [newtime]) 

where file is the file specification to change, newdate is the new date to assign to the 
file in the format yyyymmdd, and newtime is the new time to assign to the file in the 
format hhmmss. With both the NewDate and NewTime values, you must specify all 
leading and trailing zeros. The function returns a 1 if it’s successful and a 0 if it fails. 

Changing the current subdirectory (VRChBir) 

The VRChDir function changes the current subdirectory, just like the OS/2 CD com¬ 
mand. You can use this function to change to only subdirectories on the current 
drive. To change drives you must use the VRChDrive function. The syntax for the 
VRChDir function is: 


Okay = VRChDir( subdirectory) 


where subdirectory is the subdirectory to change to. If you directly specify the sub¬ 
directory rather than using a variable, you must enclose it in quotation marks be¬ 
cause the backslash (\) is a logical operator that has a special meaning to REXX. The 
function returns a 1 if it’s successful and a 0 if it fails. 

Copying files (VRCopyFile) 

The VRCopyFile function lets you copy files, just like the OS/2 Copy command. Its 
syntax is: 


Okay = VRCopyFile {before, after) 


where before is the name of the file to copy and after is the new name for the file. 
Wildcards are supported. The function returns a 1 if it’s successful and a 0 if it fails. 
This is an improvement over the OS/2 Copy command, which doesn’t support error- 
level (return codes). 

Creating a file (VRCreateFile) 

The VRCreateFile function creates a zero-length file. The syntax is: 


Okay = VRCreateFile( file) 


where file is the name of the file to create. If the file doesn’t exist, it’s created as a 
zero-length file. If the file already exists, that file is deleted and a new zero-length file 
is created. The function returns a 1 if it’s successful and a zero if it fails. 
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Creating a subdirectory (VRMkDir) 

The VRMkDir function lets you create a subdirectory. Its syntax is: 


Okay = VRMkDir {newsubdirectory) 


where newsubdirectory is the name of the new subdirectory to create. The function 
returns a 1 if it’s successful and a 0 if it fails. 


Creating an object (VRCreate) 

The VRCreate function lets you create VX-REXX objects. Its syntax is: 


Okay = VRCreate {parent, type, [property, value], [property2, value2] , [...]) 

where parent is the name of the parent object (a parent object is not required and a 
null string is used when there’s no parent), type is the type of object to create, and 
property/value is the pair of property names and values. You can use as many of 
these as you need. The function returns the internal name for the object if it’s suc¬ 
cessfully created. If it fails, a null string is returned. 


Creating an object using a stem variable (VRCreateStem) 

When the object you’re creating with the VRCreate function has a lot of properties, 
the VRCreate function can be cumbersome to use. The VRCreateStem function 
avoids this problem by allowing you to store all the properties and their associated 
values in a stem variable and then simply specify this stem variable name in place of 
a long list of properties and values. Its syntax is: 


Okay = VRCreateStem(parent, type, [Stem.]) 


where parent is the name of the parent object (a parent object isn’t required and a 
null string is used when there’s no parent), type is the type of object to create, and 
Stem is the name of the stem variable containing the properties and their values. 
Stem.O must contain the number of properties, Stem.l the first property, Stem.2 the 
value of the first property, Stem.3 the second property, Stem.4 the value of the sec¬ 
ond property, and so on. Note that the count stored in Stem.O has the number of 
components in the stem variable. The function returns the internal name for the ob¬ 
ject if it’s successfully created. If it fails, a null string is returned. 


Customize printer settings (VRPrintJobDialog) 

The VRPrintJobDialog function brings up a printer dialog box where you can cus¬ 
tomize some of the printer settings. Its syntax is: 


jobdata = VRPrintJobDialog( window, printer, [oldjobdata]) 
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where: 

■ Jobdata is a binary string that contains the job data for the given printer. This 
string can then be used the next time the function is called or by the VRPrintFile 
function. If an error occurs, it’s returned as a null string. 

■ Window is the name of the window the printer dialog box is to be modal to. 

■ Printer is the name of the printer. 

■ Oldjobdata is the old jobdata binary string. 

If oldjobdata is the keyword “default,” then the dialog box isn’t displayed and the 
settings are returned to their default value. If oldjobdata is omitted, the default 
printer settings are shown in the dialog box; otherwise, the settings in oldjobdata 
are shown in the dialog box. 

Deleting files (VRDeleteFile) 

The VRDeleteFile function deletes one or more files, just like the OS/2 Del com¬ 
mand. Its syntax is: 


Okay = VRDeleteFile( file) 


where file is the file specification to delete. You can specify a drive and path, and use 
wildcards. Unlike the OS/2 Del command, VRDeleteFile doesn’t ask for confirmation 
if you use it to delete the *.* file specification. The function returns a 1 if it’s suc¬ 
cessful and a 0 if it fails. 

Does a file exist? (VRFileExists) 

The VRFileExists function checks to see if a file or subdirectory exists. It returns a 1 
if the file or subdirectory exists and a 0 otherwise. Its syntax is: 


Okay = VRFileExists( file) 


where file is the name of the file or subdirectory to check on. 


Finding a file (VRFindFile) 

The VRFindFile function searches through a specified path, checking to see if a file 
exists. Its syntax is: 


FullName = VRFindFile( file, [path]) 

where file is the name of the file to search for (neither the drive nor path must be 
specified) and path is a list of subdirectories to search when looking for the files. 
Separate different subdirectories with semicolons, just like a path statement. If no 
path is specified, only the current subdirectory is searched. If the file is found, a fully 
qualified filename is returned. Otherwise a null string is returned. 
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Getting a value from an JNI initialization file (VRGetini) 

OS/2 and many programs designed to run under OS/2 use initialization files to store 
options regarding how they execute. These files generally have an .INI extension. The 
OS/2 system initialization file is C:\OS2\OS2SYS.INI, the OS/2 user initialization file is 
C:\OS2\OS2.INI, and the VX-REXX initialization file is C:\VXREXX\VRXEDIT.INI. The 
VRGetini function returns a setting from an .INI initialization file. Its syntax is: 

Setting = VRGetini( application, keyword, [file], ["NoClose"]) 


where: 

■ Application is the name of the application on which the initialization file VRGetini 
will operate. This is case-sensitive. 

■ Keyword is the specific value to be returned. This is also case-sensitive. 

■ File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

■ NoClose is an option to keep the file open after the operation so you can perform 
more operations on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a string with the setting if it’s successful and a null string oth¬ 
erwise. 

Getting information about disks (VRDisklnfo) 

The VRDisklnfo function returns information about a specified disk. Its syntax is: 


Okay = VRDisklnfo( option, [drive]) 

where option specifies the type of information to return and drive optionally speci¬ 
fies the drive to check. If no drive is specified, the current drive is checked. The pos¬ 
sible values for option are: 

A. Returns the number of free clusters on the disk. 

B. Returns the number of bytes per sector on the disk. 

C. Returns the total number of clusters on the disk. 

F. Returns the number of free bytes on the disk. 

S. Returns the number of sectors per cluster on the disk. 

I. Returns the total number of bytes on the disk. 

U. Returns the number of used bytes on the disk. 
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If no error occurs, the function returns a number representing the requested in¬ 
formation. If an error occurs, a -1 is returned. 

Getting information about files (VRDir) 

The VRDir function gets the same information about files as the OS/2 Dir command, 
only the VRDir function lets you store this information to REXX variables for further 
processing. Its syntax is: 


Okay = VRDir([ file], [output], [search], [mask]) 

where file is the file specification to search for (wildcards are allowed). The re¬ 
quested information on the first match is returned. If VRDir is then called again 
without a value for file, the next match is returned. This continues until all the 
matches are returned. Output specifies the information to return. Acceptable val¬ 
ues are: 

A. This returns the attributes. 

D. This returns the date in the form mm/dd/yy. 

N. This returns the file name and extension. 

S. This returns the file size in bytes. 

T. This returns the time in the form hh:mm:ss. 

If output is omitted, all this information is returned. Search controls if “special” 
files are included in the search. Possible values are: 

D. Include directories in the search. 

H. Include hidden files in the search. 

S. Include system files in the search. 

Mask restricts the type of files for which information is returned. Possible values are: 
A. Include archive files. 

D. Include directories. 

H. Include hidden files. 
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R. Include read-only files. 

S. Include system files. 

If mask isn’t specified, no files are omitted. 


Getting the disk label (VRDisRLabel) 

The VRDiskLabel returns the disk label. Its syntax is: 


Label = VRDiskLabel([disk]) 


where disk is the drive to check. If it isn’t specified, the current drive is used. An 
empty string is returned if an error occurs or if the specified drive doesn’t have a disk 
label. 

Getting the OS/2 file type (VRGetFileType) 

The VRGetFileType function lets you obtain the OS/2 file type for a specified file. Its 
syntax is: 


Type = VRGetFileType( file) 


where file is the file to obtain the OS/2 file type for. 

Is it a subdirectory? (VRIsDir) 

The VRIsDir function tests to see if the name given is the name of a subdirectory. Its 
syntax is: 


Okay = VRIsDir (sped fication) 


where specification is the name to test. The function returns a 1 if specification is 
a subdirectory and a zero otherwise. 


Listing OS/2 file types (VRListFileTypes) 

The VRListFileTypes function returns a stem variable with a list of all known OS/2 
file types. Its syntax is: 


Okay = VRListFileTypes("Stem.") 


where Stem is the stem variable to contain the list. Stem.O contains the number 
found. The function returns a 1 if it’s successful and a zero otherwise. 
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Printing a file (VRPrintFile) 

The VRPrintFile function places a file in the printer queue to be printed. It doesn’t 
return control to VX-REXX until the file has been queued. The syntax is: 

Okay = VRPrintFile(printer, filename, [jobdata], [title]) 


where: 

■ Printer is the name of the printer to use. This name is returned by the ListPrint- 
ers Method and the DragPrint event. 

■ Filename is the name of the file to print. You can include a drive and path, but 
wildcards aren’t allowed. 

■ Jobdata is the data returned from the VRPrintJobDialog function. If omitted, the 
default printer settings are used. 

« Title is the name that appears in the print job queue. 

To improve the overall program speed, start a separate thread to handle printing. 

Putting a value into an .INS initialization file (VRSetlni) 

The VRSetlni function inserts a setting into an .INI initialization file. Its syntax is: 

Okay = VRSetlni {application, keyword, value [file], ["NoClose"]) 

where: 

* Application is the name of the application whose initialization file VRSetlni is to 
operate on. This is case-sensitive. 

■ Keyword is the specific value to be set. This is also case-sensitive. 

■ Value is the new value for the keyword . 

File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

■ NoClose is an option to keep the file open after this operation so you can perform 
more operations on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a 1 if it’s successful and a 0 otherwise. 

Removing a subdirectory (VRRmDir) 

The VRRmDir function removes an empty subdirectory. Its syntax is: 


Okay = VRRmDir( subdirectory) 
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where subdirectory is the name of the subdirectory to remove. Only empty sub¬ 
directories can be removed. The function returns a 1 if it’s successful and a 0 oth¬ 
erwise. 


Removing a value from an .INI initialization file (VRDellni) 

The VRDellni function allows you to delete a value from an .INI file. Its syntax is: 

Okay = VRDellni( application, keyword, [file], ["NoClose"]) 


where: 

■ Application is the name of the application whose initialization file VRDellni is to 
operate on. This term is case-sensitive. 

■ Keyword is the specific value to be removed. This term is case-sensitive. 

■ File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

■ NoClose is an option to keep the file open after this operation so you can perform 
more operations on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a 1 if it’s successful and a 0 if it fails. 


Removing an object (VRDestroy) 

The VRDestroy removes (or destroys) an object and all its children. Its syntax is: 


Okay = VRDestroy( object) 


where object is the object name or handle. The function returns a 1 if it’s successful 
and a 0 if it fails. 


Renaming a file (VRRenameFile) 

The VRRenameFile function lets you rename a file. It’s more useful than the OS/2 Re¬ 
name command as it accepts a full path for both the source and target names. Its 
syntax is: 


Okay = VRRenameFile( old, new) 


where old is the old name and new is the new name. If a new path is specified for the 
file in new , the files are moved. The function returns a 1 if it’s successful and a 0 if it 
fails. 
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Showing the full filename for a file (VRExpandFileName) 

The VRExpandFileName function expands a filename into its fully qualified file¬ 
name. Its syntax is: 


FullName = VRExpandFileName( file) 


where file is the file specification to expand. Unlike many commercial utilities, VR¬ 
ExpandFileName doesn’t search for the file on the hard drive. Rather, it simply re¬ 
solves relative paths, such as .A, and adds the full drive and path to a file if it’s in the 
current subdirectory. Its normal use is to expand relative paths. 

Sorting a stem variable (VRSortStem) 

The VRSortStem function sorts a stem variable into alphabetical order and stores 
the results to either the same stem variable or a new stem variable. The syntax is: 


Okay = VRSortStem("Stem.", ["NewStem."], [order], [case]) 


where: 

■ Stem is the name of the stem variable to sort. It must be configured, so Stem.l 
stores the first value, Stem.2 the second, and so on. 

■ NewStem is the name of the new stem variable to store the sorted values to. If it’s 
omitted, the original stem variable is used. 

■ Order is either ‘Ascending’ or ‘Descending’ to indicate the sort order. The default 
is ascending. 

■ Case is either ‘Sensitive’ or ‘Insensitive’ to indicate if the sort should be case-sen¬ 
sitive. The default is insensitive. 

The function is a very quick and easy way to sort a stem variable. It returns a 1 if the 

sort was successful and a 0 otherwise. 

Splitting a filename into parts (VRParseFileName) 

The VRParseFileName function splits a filename into its parts. The syntax is: 


Part = VRParseFileName( file, [option]) 


where file is the filename to parse and option describes the information to be re¬ 
turned. The option can include any sequence of the following, and the information 
that’s returned is in the same sequence: 

D. Drive letter. 


E. File extension. 
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N. Filename. 

P. Path to the file. 

The colon and backslash aren’t included in the string that’s returned if they’re the 
last characters. 

Splitting a filename into parts (VRParseFilePath) 

The VRParseFilePath function splits a file into its parts just like the VRParseFile- 
Name function, except VRParseFilePath doesn’t require that the file exists. The syn¬ 
tax is: 


Part = VRParseFilePath( file, [option]) 


where file is the filename to parse and option describes the information to be re¬ 
turned. The option can include any sequence of the following, and the information 
that’s returned is in the same sequence: 

D. Drive letter. 

E. File extension. 

N. Filename. 

P. Path to the file. 

The colon and backslash aren’t included in the string that’s returned if they’re the 
last characters. 

What is the current drive? (VRCurrDrive) 

The VRCurrDrive function returns the current drive. Its syntax is: 


Okay = VRCurrDrive() 


This function returns the current drive letter, capitalized and followed by a colon. 

What is the current subdirectory? (VRCurrOir) 

The VRCurrDir function returns the current subdirectory. Its syntax is: 


Okay = VRCurrDir( [drive] ) 


where drive is the optional drive from which to return the current subdirectory. If 
drive isn’t specified, the current drive is used. 
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Function Summary Program 

To help you find the functions you need quickly, I created Function. Function is a 
program that has buttons for each type of file activity VX-REXX is capable of per¬ 
forming. Click on a button and the name of the function will be shown at the top right 
of the screen, a summary of the function below that, and the syntax of the function 
at the bottom of the screen (see Figure 12.1). Click on another button and the in¬ 
formation will be changed to reflect your new choice. 

The Click event for each button creates three variables containing the function 
name, description, and syntax. They then call a common subroutine called Display to 
display that information on the screen. The code for that subroutine is: 

/*:VRX */ 

Display: 

IF Showing = "NO" THEN 
DO 

Showing = "YES" 

Okay = VRSet("DT_1", "Visible", 1) 

Okay = VRSet("DT_2", "Visible", 1) 

Okay = VRSet("DT_3", "Visible", 1) 

Okay = VRSet("DT_Name", "Visible", 1) 

Okay = VRSet("DT_Describe", "Visible", 1) 

Okay = VRSet("DT_Syntax", "Visible", 1) 

END 

Okay = VRSet("DT_Name", "Caption", Name) 

Okay = VRSet("DT_Describe", "Caption", Description) 

Okay = VRSet("DT_Syntax", "Caption", Syntax) 
return 
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Figure 12.1 Using the Functions program to get information about the VRSortStem function. 
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The first ten lines make the Descriptive Text objects visible the first time a button is 
clicked. Before that, they’re invisible. The last three lines display the three variables 
in their respective windows. 

Function won’t run on a VGA display. There’s a special version of Function, 
however, called Fun-VGA, which is designed especially for VGA displays. While 
the entire display is not visible during design, it can be seen when the program is 
running. 


Summary 

Tables 12.1 and 12.2 summarize the VX-REXX functions discussed in this chapter. 


TABLE 12.1 Functions for Working with VX-REXX Objects 


VX-REXX function 

VRError 

VREvent 

VRFileDialog 

VRFini 

VRGet 

VRInfo 

VRInit 

VRIsValidObject 

VRLoad 

VRLoadSecondary 

VROptions 

VRMessage 

VRMessageStem 

VRMethod 

VRPrompt 

VRSet 

VRVersion 

VRWindow 

VRWindowPath 


Purpose 

Reads the last VX-REXX error message. 

Returns the event string for the next event to be processed in a program. 

Offers a convenient way for the user to pick a filename when one is required. 
Terminates the VX-REXX programming environment. 

Polls VX-REXX objects and obtains information from them. 

Returns information about the last event returned from the VREvent function. 
Initializes the VX-REXX programming environment. 

Tests to see if the specified VX-REXX object or Presentation Manager window’s 
handle exists. 

Loads the description of a window from a file. 

Loads the description of a secondary window from a file. 

Configures VX-REXX to behave like version 1.01 when the VRGet, VRSet, or 
VRMethod functions receive an invalid object name. 

Displays an error message and gives the user several alternatives for resolving 
the problem. 

Displays an error message and gives the user several alternatives for resolving 
the problem, where all the components are stored in a stem variable. 

Invokes the method of an object. 

Dislays a prompt to the user in a dialog box and then obtains a lengthy response 
from the user. 

Changes the properties of an object. 

Returns the version number and date of the VX-REXX dynamic link library. 
Returns the internal name of the primary window for the current program. 
Returns the path of the primary windows for the current program. 
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TABLE 12.2 Functions for Working with OS/2 Objects 

VX-REXX function Purpose 


VRChAttr 

VRChDir 

VRChDrive 

VRCopyFile 

VRCreate 

VRCreateFile 

VRCreateStem 

VRCurrDir 

VRCurrDrive 

VRDeleteFile 

VRDellni 

VRDestroy 

VRDir 

VRDisklnfo 

VRDiskLabel 

VRExpandFileName 

VRFileDate 

VRFileExists 

VRFindFile 

VRGetFileType 

VRGetlni 

VRIsDir 

VRListFileTypes 

VRMkDir 

VRParseFileName 

VRParseFilePath 

VRPrintFile 

VRPrintJobDialog 

VRRedirectStdIO 

VRRenameFile 

VRRmDir 

VRSetFileType 

VRSetlni 

VRSortStem 


Changes the archive, hidden, read-only and system attributes of a file. 
Changes the current subdirectory. 

Changes the current drive. 

Copies files. 

Creates OS/2 objects. 

Creates a 0-length file. 

Creates OS/2 objects using a stem variable to store the object properties. 
Returns the current subdirectory. 

Returns the current drive. 

Deletes one or more files. 

Deletes a value from an .INI initialization file. 

Removes (or destroys) an object and all of its children. 

Returns directory information about a file. 

Returns information about a specified file. 

Returns the disk label. 

Expands a filename into its fully qualified filename. 

Changes the date and/or time associated with a file. 

Checks to see if a file or subdirectory exists. 

Searches through a specified path, checking to see if a file exists. 

Returns the OS/2 file type for a specified file. 

Returns a setting from an .INI initialization file. 

Tests to see if the name given is the name of a subdirectory. 

Returns a stem variable containing all the known OS/2 file types. 

Creates a subdirectory. 

Splits a filename into its parts. Requires that the file exist. 

Splits a filename into its parts. Does not require that the file exist. 

Places a file in the printer queue to be printed. 

Brings up a printer dialog box where you can customize some of the printer 
settings. 

Redirects the standard I/O to the VX-REXX console window. 

Renames a file. 

Removes an empty subdirectory. 

Sets a file type. 

Inserts a setting into an .INI initialization file. 

Sorts a stem variable into alphabetical order. 



Chapter 

13 

VX-REXX Sample Programs 


VX-REXX comes with a number of useful sample programs, many of which demon¬ 
strate the concepts I’ve discussed so far. While these VX-REXX sample programs are 
briefly summarized in Chapter 23 along with my example programs and the other 
programs that come with this book, I want to provide a more detailed accounting of 
these programs now for review. 

Some of these programs demonstrate topics in the more advanced section of this 
book. I’ve decided to include those here as well rather than splitting the material up. 
You can consider these programs to be previews of things to come. 


Where to Find These Programs 

During installation, VX-REXX creates a \SAMPLE subdirectory for the sample pro¬ 
grams included with the program. There are no files in the \SAMPLE subdirectory. 
Rather, VX-REXX creates a subdirectory off the \SAMPLE subdirectory for each 
sample program. For example, the subdirectory for the Bounce program is \SAM- 
PLEVBOUNCE. VX-REXX doesn’t store any files in these subdirectories either. 
Rather, it creates a \SOURCE subdirectory to contain them. So the program files for 
Bounce are stored in the \SAMPLE\BOUNCE\SOURCE subdirectory. For some of the 
samples, it also creates a \BIN subdirectory to contain the .EXE compiled file and an 
icon for the program. For Bounce, this would be \SAMPLE\BOUNCE\BIN. 


Bounce 


Bounce displays an image of the earth against a black background. The image moves 
around the screen in a regular pattern. When it hits one of the four sides, it bounces 
off and continues along its path. 
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Figure 13.1 shows the user interface for Bounce. The movement is controlled 
by the Timer object that’s barely visible in Figure 13.1. It’s configured as hidden 
so it doesn’t show in the final program. The picture of the earth is BOUNCE.ICO, 
displayed in a PictureBox object. The PictureBox object is tiny and hard to see 
against the black background, but it’s located at the top left of the screen. The 
Trigger event of the Timer object moves the PictureBox object around on the 
screen. 


Button 

Button displays four PushButton objects on the screen. Initially, they’re gray and dis¬ 
play the message “Push Me!” The first time you click on them they change to a red 
background and display “Red.” The next time they change to yellow and display “Yel¬ 
low.” After that, they alternate between red and yellow. 

Figure 13.2 shows the user interface for Button. The program uses the VRGet 
function to read the current status of the buttons and the VRSet function to change 
the status of the buttons. VRGet and VRSet are two of the most commonly used VX- 
REXX functions. 
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Figure 13.1 The Bounce user interface. 
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Figure 13.2 The Button user interface. 


Calculator 

Calculator is a fairly nice calculator program. It performs addition, subtraction, mul¬ 
tiplication, division, and percentages. It also has a single memory function. 

Figure 13.3 shows the user interface for Calculator. It uses the same PushButton 
object name for all the digits and all the operations, so it’s a good illustration of how 
to take different actions depending on the caption of the object. It uses a Descriptive 
Text object to display numbers and the memory indicator. 

Calculator also demonstrates the KeyPress event. While running, you can enter 
numbers by pressing on the appropriate numbers on the keyboard rather than using 
a mouse. The keyboard also lets you enter the operator, with Enter functions for the 
equal sign, F5-F8, and C and E for Clear and Clear Entry respectively. 


DDE Explorer 

DDE Explorer is a sample program that illustrates how to use the DDEClient object 
to interact with applications that support the DDE interface. 
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VX-REXX - CALC (C:\QS2WXREXX\SAMPLES\CALCULA1\S0URCE 
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Figure 13.3 The user interface for the Calculator program. 


Figure 13.4 shows the user interface for DDE Explorer. DDE Explorer uses multi¬ 
ple windows. It has a control window along with windows to connect to a DDE ap¬ 
plication, execute a command, issue a request, and insert a value. In addition to the 
DDEClient object and multiple windows, DDE Explorer uses PushButton, ListBox, 
and EntryField objects. Figure 13.5 shows DDE Explorer in action, using the Con¬ 
nect option to list the available DDE servers. 


DragDrop 

DragDrop illustrates using the Container object and drag-and-drop procedure in 
programs. It shows two Container objects on the screen with four information icons 
in each Container object. As these icons are dragged from one Container object and 
dropped into the other, it displays information about the icons on the screen. 

Figure 13.6 shows the user interface for DragDrop. Note that only two Container 
objects are visible. The icons are added by the program as it executes. Figure 13.7 
shows DragDrop running before any of the icons have been moved. You move an icon 
by pointing to it with the mouse cursor and holding down the right mouse button as 
you drag it to the other Container object. 

DragDrop uses the REXX Say command to display information, rather than going 
through a VX-REXX object like a Descriptive Text object. This causes OS/2 to display 
the information in a special window. Figure 13.8 shows DragDrop after several icons 
have been moved. An OS/2 window like the one shown in Figure 13.8 will always ap¬ 
pear whenever a VX-REXX program uses the REXX Say command. This window 
doesn’t automatically close when the program terminates; you must do that manually. 
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Figure 13.4 The DDE Explorer user interface. 
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Figure 13.6 The user interface for DragDrop. 
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Figure 13.7 DragDrop running before any icons are moved from 
one Container object to the other. 
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Figure 13.8 DragDrop running after icons are moved from one Container object to another. Since Drag- 
Drop uses the REXX Say command, OS/2 displays the information in a special window. This window is 
separate from VX-REXX and is managed by OS/2. 


File Browser 

File Browser displays the files and subdirectories on your hard disk and lets you click 
on different icons to move around, viewing the contents of different subdirectories. 
It uses a Container object, so all the views supported by the Container object are 
supported. It doesn’t let you view the contents of individual files, however, as the 
name implies. 

File Browser is a clever implementation of a Container object and contains little 
else but a menu to support it. Figure 13.9 shows File Browser running and showing 
the contents of the \FILE_BRO subdirectory in Icon view. Figure 13.10 shows File 
Browser running, showing the contents of the \VXREXX subdirectory in Text Tree 
view. The program is maximized to show as many of the files as possible. 


Hint and Help 

Hint and Help is a demonstration program that asks users for their name and a pass¬ 
word. However, its main purpose is to illustrate adding hints and help to programs. 

Figure 13.11 shows the user interface for Hint and Help. It uses a couple of Entry- 
Field objects to get information from the user, a couple of PushButton objects, and a 
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Figure 13.9 File Browser running and showing the contents of 
the \FILE_BRO subdirectory in Icon view. 
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Figure 13.1 0 The File Browser program running and showing the contents of WXREXX in Text Tree view. 
File Browser has been maximized to show as many files as possible. 
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couple of Descriptive Text objects to display instructions. When you move the cur¬ 
sor over an object, the program displays a hint at the bottom of the Hint and Help 
screen, much like balloon help with Macintosh System 7. If you press FI, Hint and 
Help displays pop-up help, as shown in Figure 13.12. 


Hint and Help Example 


Name: 


Password: 


OK 


Help 


Type your password ( will not be disp layed) 


Figure 13.11 Hint and Help 
running. Note the hint at the 
bottom of the screen. 
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Figure 13.12 Hint and Help after the user has pressed FI to request help. 
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Hocus Focus 

Hocus Focus displays the Presentation Manager handle for the window that is currently 
the focus. Periodic readings of the Presentation Manager are keyed by the Trigger event 
of a Timer object. When Hocus Focus runs, it initially runs minimized. You must then use 
Ctrl-Esc to switch to it and see it. Figure 13.13 shows Hocus Focus running. As you click 
on different windows under Presentation Manager, Hocus Focus displays their handles. 

Mind Game 

Mind Game is a fairly good logic game. In fact, I compiled it and installed it to my 
desktop so I could take a brief rest when the computing gets too complex. 

Mind Game fills a row of four blocks with a random selection of six colors, but 
doesn’t show that mixture to the user. The user then has ten guesses to figure out 
the color for each of the four blocks. After each guess, it tells you how many you got 
right but doesn’t tell you which positions were correct. You use the information from 
each successive guess to narrow your guesses and find the solution. 

Figure 13.14 shows the user interface for Mind Game. The top right contains six 
PushButton objects for selecting the color of the next guess and a larger PushButton 
object that shows the currently selected color. Below these is a very large button you 
click on once you’ve entered the colors for your guess. It’s deactivated until you’ve 
entered your guess. 

The left side has a grid of 40 buttons, ten rows of four each. You enter your guess 
beginning on the bottom row. While it’s difficult to see in Figure 13.14, each row has 
a Descriptive Text object to its right that shows the number of correct and incorrect 
guesses. After each turn, this information is left on the screen so you can refer to it 
in making future guesses. Along the bottom are four more PushButton objects that 
display the correct answer at the end of the game. 

Mind Game is probably the best demonstration package that comes with VX- 
REXX. In addition to illustrating PushButton objects, it uses a dialog box, the VX- 
REXX functions, stem variables, and menus. 


MMW 


VX-REXX works with two types of windows: modeless and modal. A modeless win¬ 
dow allows the program that created it and all that program’s children to continue to 
run while it’s active, while a modal window disables the program that created it and 
all that program’s children while it’s running. MMW allows you to experiment with 
both types of windows by clicking on different PushButton objects to create differ¬ 
ent types of windows. 




The caption of this window is the PM window handle 
of the window that has the focus. 

?HWND7c4052M 


Figure 13.13 Hocus Focus running, displaying the Presentation Manager win¬ 
dow handle for a window. 
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VX-REkk — MINDGAME (C:\OS2WXREXX\SAMPLE3\MIND_GAnSOURCE\ 
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Figure 13.14 The user interface for Mind Game, which is a game where the user tries to guess a pat¬ 
tern of four colors. 
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Figure 13.15 The MMW program after one modeless window is 
opened with the top button. The user can open multiple versions 
of this same window by clicking on the top button repeatedly. 


The user interface for MMW is rather plain, consisting of one Descriptive Text 
object to display text and three PushButton objects to perform various tasks. Fig¬ 
ure 13.15 shows MMW running after I’ve created a single modeless window by 
clicking on the top button. Since this window is modeless, the original program re- 
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mains active. If I clicked on the top button again at this point, another version of 
this window would be created. 

Figure 13.16 shows MMW running after the middle button was clicked to create a 
second modeless window. Like the first, this window leaves the original window and 
all its children active. Figure 13.17 shows MMW running after the bottom button was 
clicked to create a modal window. The modal window deactivates the program that 
created it and all the children of that program until the modal window is closed. So 
at this point both the main MMW window and the modeless windows are inactive. 
Closing the modal window reactivates them. 


Movies 


Movies demonstrates how to use the multimedia extensions of OS/2 to play movies 
using VX-REXX. You can play the movies using the current thread or in a separate 
thread, so the program also demonstrates how to use threads. Figure 13.18 shows 
the user interface for Movies. 


Notebook 


Notebook displays a property notebook for a PushButton object that allows the 
user to change the color and size of a button. It demonstrates how to create a 
property notebook and in this respect is similar to my sample program of the same 
name. Figure 13.19 shows the program running. You must first click on the button 
to display the property notebook. 
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Figure 13.16 MMW after a second modeless window is opened with the 
middle button. Since the first window was a modeless window, the 
main program will remain active so this second window can be created. 
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Figure 13.18 The Movies user interface. Movies uses the multimedia extensions 
of OS/2 to run movies on either the current thread or a separate thread. 
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Figure 13.19 The Notebook program, displaying a property notebook created by the program to control 
the appearance of the PushButton object. 



Figure 13.20 Popup running with a pop-up menu displayed. 
Users can change the color and caption of the bottom button 
with this menu. 


Popup 

Popup demonstrates how to construct pop-up menus. In this sample program, these 
menus let the user change the color and caption of three PushButton objects. Figure 
13.20 shows Popup running. In this figure, a pop-up menu is displayed for the third 
button. 

Printing 

Printing is a sample program for sending files to the printer. It uses the ListPrinters 
method, and the VRPrintJobDialog and VRPrintFile VX-REXX built-in functions. 

Figure 13.21 shows the program running. Note that it automatically displays the 
available printers (only the Apple LaserWriter is available in this figure). Figure 
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13.22 shows the Print Setup menu. Note that the program automatically reads the 
settings from the currently selected printer. Figure 13.23 shows the Options sub¬ 
menu of the Print Setup menu. Again, note that the program automatically reads the 
settings from the currently selected printer. 


Q+E Text 

Q+E Text displays a database entry screen for employee data. It uses the VXQE and 
QELIB libraries to access the employee database, which is stored in EMP.TXT. 


File to print: 


Find 


Printer: 



Print | Print setup... j Cancel 


Figure 13.21 The Printing program running. Note that the 
name of the available printers is displayed automatically. 
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Figure 13.22 Printing showing the Print Setup menu. Note that it 
reads the current settings from the printer. 









186 Introductory VX-REXX Topics 



d PostScript Job Properties 


Print T-— ^ * 

©Printer: Apple LaserWriter 
QRaw Postscript file 
) Encapsulated Postscript file 


Timeouts Secs 


Printing Effects— 

E3 FUp top to bottom 
l Flip left to right 
□ Draw inverted 


Uncollated copies: Fji I 


Cancel 


Figure 13.23 Print showing the Options menu of the Print 
Setup menu. It too reads the current settings from the printer. 


RGB 

RGB displays three Slider objects and one ValueSet object with four cells. Initially, the 
four cells are colored red, green, blue, and white. Once the user has selected a partic¬ 
ular cell in the ValueSet object, he or she can use the three ValueSet objects to alter the 
mixture of red, green, and blue in that cell, thus changing its color. In addition to illus¬ 
trating how to use the Slider and ValueSet objects, this program illustrates how to use 
RGB color settings in a ValueSet object. Figure 13.24 shows the RGB program running. 

Sample Database 

Sample Database (SampleDB) shows how to use VX-REXX in conjunction with ei¬ 
ther Database 2 OS/2 (DB2/2) or the extended services for OS/2 Database Manager 
to manage a small database. (These are separate programs that don’t come with 
OS/2 or VX-REXX, so you might not be able to run this program.) Sample Database 
accesses the sample database using the Database Manager REXX application pro¬ 
gramming interface (API) and gives you a simple view of the data. It also gives you 
simple tools for viewing the data. 

Scan 

Scan is a macro for the OS/2 Enhanced Editor. It scans the file you’re currently edit¬ 
ing and displays a dialog box listing every REXX label it finds. You then double-click 
on the label name to jump to that point in the file. Scan illustrates using the Make 
Macro option of the Project menu. 
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The program automatically scans the file when executed, so the user doesn’t need 
any objects to tell the program to start. A ListBox object displays the label names 
and two PushButton objects, one to jump to the highlighted label and a second to 
cancel the macro. 

Figure 13.25 shows using the Enhanced Editor to edit a file, TODO.CMD in this 
case. The Command Dialog command has been selected from the Command menu 



Figure 13.24 RGB running. All three Slider objects control 
the color mixture of the currently highlighted cell in the Val- 
ueSet object. 



Figure 13.25 Using the Enhanced Editor Command dialog box to run the Scan program. The file be¬ 
ing edited is TODO.CMD. 
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and the command to start the macro, RX SCAN, has already been entered. Figure 13.26 
shows the display that Scan presents after it has scanned the entire REXX file. At this 
point, you have the option of jumping to one of the displayed subroutine names or can¬ 
celling the macro. 


Threads 


OS/2 has the ability to “spin off’ complex or time-consuming activities to their own 
thread. This thread then runs in the background. This allows the main process to 
continue instead of waiting on the complex or time-consuming activity. Threads 
demonstrates how to create multithreaded applications. 

Each time the user clicks on the Spawn New Thread button, a new thread is cre¬ 
ated with a dialog box where the user can enter text. If the user presses Return or 
clicks on the Send To Parent button, this text is returned to the main application and 
removed from the display of the thread’s dialog box. 

Each thread is given a number, starting with 2 and continuing sequentially. 
(The main program is number 1.) By highlighting the number of a thread in the 
main application, the user can kill that thread by clicking on the Halt Selected 
Thread button. Figure 13.27 shows the Threads program running after six threads 
have been created. 





___PIP, 

File Edit Search Options 

rM — — — -C nJ 1 « . 

Command Help Labels 


stir if f pi 

if 


/* NAME: 
PURPOSE: 
VERSION: 
DATE: 

COPYRIGHT: 


TODO.C] 
Mainta 
1.00 
octobe 
1994 M- 


ADD 

BACKWARD 

CHANGE 

DELETE 

DISPLAY 

EXIT 

FIGUREOUTMESSAGE 

FILEIT 

FORWARD 

KILLIT 


r : „Lc 

HP 





; 

[OK 


Cancel 


j . 



5 * * 



HelpCheck « ARG(l) 

IF HelpCheck = ■/? 
DO 

SAY "Todo Prog 
EXIT 
END 

call setup 

CALL ReadData 


DO FOREVER 
CALL Display- 

Character = SysGetKey(NoEcho) 

SELECT 

WHEN Character = "A" THEN CALL Add 
WHEN character - B a H THEN Call Add 


m 


Line 1 of 323 Column 


1 1 File Insert 


Figure 13.26 After Scan finishes scanning the current command file, it presents a list of all the labels; you 
can switch to one just by clicking on its name. 







VX-REXX Sample Programs 189 


Thread 2 


lype 


iThis is #2 


Thread 3 


lype 
IThis is #3 


; Thread:. A : 


lype 

I |And so on... 


Send to parent 


Send to parent 


| 2 

rV 

Spawn New Thread j 

1 


Send to parent 


V13 
\':\4 


: - 



Thread :5 :: 


lype 

These could be running 


Halt Selected Thread 


Messages From Threads: 


Pressing enter sends text back 


Program is thread J1 


Send to parent 



to the parent that created 
the thread. 

■VJ 


Send to parent 




V- 



Thread i 


lype 

(complex operations 


fS\ I bread / 

Type 


Sthat take a lot of time. 


Send to parent 


Figure 13.27 The Threads program after six threads are created. These will continue processing when the 
main program is stopped. 


Update DB Sample 

Like the Sample Database program, the Update DB Sample depends on either the 
Database 2 OS/2 program (DB2/2) or the Extended Services for OS/2 Database Man¬ 
ager to work with a database. (These are separate programs that don’t come with 
OS/2 or VX-REXX, so you might not be able to run this sample program.) Update DB 
Sample displays employee records from the Staff table of the Sample database. The 
user can delete or modify viewed records or add new records. 

Window Controller 

Window Controller lists all the open Presentation Manager windows in a Container 
object. It also allows you to send keystrokes to these windows or “shake” them by 
slightly altering their position on the screen. Figure 13.28 shows the program running. 


Summary 

This chapter summarizes the sample programs that come with the VX-REXX pack¬ 
age. For more detailed information, please consult either the written or online VX- 
REXX manuals. 
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Figure 13.28 The Window Controller program running. Note the use of plus signs in the Container ob¬ 
jects to indicate a child record below a parent, and the minus sign to indicate that a record can be col¬ 
lapsed. 
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Working with Multiple Windows 


So far, most of the programs you’ve written were designed in a single window. The 
few that used a second window generally used a VX-REXX function to pop up the 
window in order to get information—so VX-REXX handled the window manage¬ 
ment. Even with the Notebook program, which used multiple windows to create a 
property notebook, the multiple windows were pulled together into the property 
notebook by VX-REXX, so it managed the extra windows. In this chapter, you’ll see 
how to add and manage your own windows. 

The first window you create for a program is called its primary window . Any 
additional windows you add to your program are called secondary windows. 
When a window opens another window, the original window is said to be the par¬ 
ent and the window it opens is called the child. As in real life, a parent can have 
many children and any child window can open its own window. It becomes the par¬ 
ent to that child window and that child window becomes the grandchild of the orig¬ 
inal window. 

VX-REXX has two types of windows: modeless and modal. The code for a mode¬ 
less window is stored in the same file as the first window (the primary window). A 
modeless window shares subroutines and variables with the primary window and 
doesn’t disable the primary window when it runs. That is, the primary window re¬ 
mains active while the modeless window is displayed. This allows the user to switch 
between the windows. On the other hand, a modal window is stored in a separate 
file, so it can’t share subroutines or variables with the window that activated it. When 
a modal window is activated, it automatically disables its parent window, plus any 
children of that parent window. 
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Built-in Secondary Windows 

VX-REXX has four functions that automatically load secondary windows. They take 
care of all aspects of managing their windows, so the programming is completely 
transparent to the programmer. These functions are: 

VRFileDialog. This prompts the user for a filename to use for saving or loading 
files. 

VRMessage. This displays a message and waits for confirmation. The message it 
displays is under the control of the programmer. 

VRMessageStem. This also displays a message and waits for confirmation, only us¬ 
ing a stem variable. 

VRPrompt. This prompts users for a string, such as their name. 

I advise that you use these easy-to-use functions where they apply rather than go¬ 
ing to the trouble of coding a secondary window. These were discussed in detail in 
Chapter 7. 

Modeless Windows 

A modeless window has its code stored in the same file as the primary window, so it 
can share subroutines with the primary window. When a modeless window is active, 
its parent and all of its parent’s children remain active. When the parent is closed, 
minimized, or restored, the modeless window is also closed, minimized, or restored. 
Optionally, the modeless window can be configured to move with the parent. 


The primary window 

Of course, the first step to creating a secondary window is to design the primary win¬ 
dow. While the primary window doesn’t have to be finished before you start on the 
secondary window, you would generally begin building the primary window as a 
foundation and add secondary windows as they’re required to address particular 
needs that can’t be handled by the primary window. 

As an example, let’s create a program called Window-1. Window-1 is a demonstra¬ 
tion program that simply loads three different modeless windows when the user 
clicks on separate PushButton objects. The user interface for Window-1 is shown in 
Figure 14.1. 


Window List window 

Note that the Window List window is shown on the right side of the screen in Figure 
14.1. This is the tool you use to create new windows, delete existing windows, open 
an existing window to work on it, and close an existing window so you can work on 
other objects. Basically, it provides all the tools you need to manage windows while 
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Figure 14.1 The Window. 1 user interface with the primary window complete. Note the Window List window. 
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Figure 14.2 Creating a secondary window for Window-1 by selecting New Window from the Window List 
window. 


you’re working on them except renaming a window—which is handled by the win¬ 
dow’s property notebook. Once the program is running, the program must manage 
the windows. Bring up the Window List window by selecting it from the Window 
menu or by pressing F8. 

Creating a modeless secondary window 

To create a secondary window, select New Window from the menu in the Window 
List window. This creates an empty window, as shown in Figure 14.2. Since both win¬ 
dows are now visible, with the new one on top of the old one, the screen looks very 
cluttered. You can use Close from the menu in the Window List window to close the 
primary window Of course, you must first select the primary window in the Window 
List window. 
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Modeless windows that you create in this fashion are stored in the same file as the 
primary window. As a result, when you select Save or Save As from the menu to save 
the program, both the primary window and all the secondary windows are automat¬ 
ically saved by the single command. 

When you create a new window, VX-REXX automatically generates a name for it 
using the form SW_x, where x is a number starting at 1 for your first secondary win¬ 
dow and going up by 1 each time. You can change this to something meaningful us¬ 
ing the Name field in the window’s property notebook. 

Once you’ve created the secondary window, you design its contents just as you 
would a primary window. Figure 14.3 shows a secondary window with a Descriptive 
Text object added to display a message and a PushButton object added to close the 
window. The name of the window has been changed to Windowl. 

As a general rule, the minimize and maximize buttons aren’t necessary for a mode¬ 
less secondary window because minimizing and maximizing are handled by the pri¬ 
mary window. You generally want the window to have a title bar, though, because 
you’ll use this to move the window on the screen. If you want the window to move 
when its parent is moved, set the MoveWithParent property. 


Using a modeless secondary window when the program is running 

Secondary windows aren’t automatically loaded by VX-REXX, nor would you want 
them to be. Most of the time, you’ll want the secondary window to pop up when the 
user triggers some event that brings the secondary window into play. If you want the 
secondary window to be loaded automatically by VX-REXX when the program starts, 
just add the appropriate code to the Init section. You might, for example, load all the 
secondary windows in the Init subroutine but make them invisible. Since making an 
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Figure 14.3 A finished secondary window for Window-1. The other two will look very similar, only with 
different numbers. 
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invisible object visible is much faster than loading it from disk, this can dramatically 
speed up the operation of a program that uses a lot of secondary windows. 

The VRLoadSecondary VX-REXX function loads a secondary file. Its syntax is: 


Okay = VRLoadSecondary("Window") 


where Window is the name of the secondary window to load. VRLoadSecondary re¬ 
turns the internal name of the loaded window—which won’t match the name you 
gave it while designing the window If for some reason VRLoadSecondary fails, it will 
return a null string. 

There’s one consideration you need to make. The VRLoadSecondary function 
doesn’t take a secondary window and load that window into memory. Rather, it runs 
a subroutine that creates another window and loads it into memory. The difference 
is subtle but important. The subroutine just creates a window and places it on the 
screen, so if you run the subroutine again it will create another window and place it 
on the screen. 

You can see this in the MMW sample program that comes with VX-REXX. Run the 
program and click on the first button to create a modeless window. Now drag that 
window to another location on the screen and click on the button again so another 
window is created. Of course, the only reason for moving the first window was so you 
would notice the second window, since it otherwise would have been created exactly 
on top of the first window. 

Most of the time the secondary window pops up to handle a specific process or 
display information, so you don’t usually want multiple copies of a window loaded. 
You have two options for doing this. First, you can maintain a flag to indicate when a 
secondary window has been opened and open the window only if the flag indicates 
that it isn’t already open. Second, you can have the subroutine that opens the sec¬ 
ondary window disable the object that triggers loading the secondary window. We’ll 
take the second approach with Window-1, and illustrate the first approach later. 

In the example, the windows have the same name except for the number on the 
end, as do the PushButton objects used to open the windows. That makes it easy to 
open all the windows in a common subroutine. Each Click event for the three but¬ 
tons issues a command like CALL Open 1, only using the number of the window to 
open. The Open subroutine is as follows, with line numbers added for reference: 


1. 

Open: 


2 . 

Number 

= Arg(l) 

3 . 

Window 

= "Window" I ! Number 

4 . 

Button 

= "Load_Window" ! ! Number 

5 . 

Okay = 

VRLoadSecondary(Window) 

6 . 

Okay = 

VRSet(Button, "Enabled", 0) 

7 . 

return 



Line 2 gets the number of the window, which is being passed as an argument, and 
stores it to a variable. Line 3 creates a variable containing the name of the window to 
load. Line 4 creates a variable containing the name of the PushButton object to dis¬ 
able. Line 5 loads the window, and line 6 disables the PushButton object. 
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Closing a modeless secondary window when the program is running 

A secondary window remains open until something closes it. If it has a system menu, 
the user can use that to close it. However, this isn’t a very professional way to struc¬ 
ture your programs. It also makes it impossible to track window usage and avoid mul¬ 
tiple copies of a window, but at the same time allows the user to reopen a secondary 
window that has been closed. If you do depend on the system menu for closing the 
window, no code is required in your window to handle window closings. Other alter¬ 
natives for closing the window are: 

® Give the user a menu option to close the window. Menus are discussed in Chapter 15. 

■ Give the user a PushButton object to close the window. This is the approach we’ll 
take with the Window-1 program, as you’ve already seen in the design of the sec¬ 
ondary windows. 

■ Close the window automatically when some event has happened or an amount of 
time has passed. When you do this, the code to close the window is appended to 
the appropriate place in the program. 

No matter how the command to close the window is generated, you have two alter¬ 
natives on how to handle it. The first is to make the window invisible using a com¬ 
mand like this: 


Okay = VRSet("windowl", "Visible", 0) 

where Windowl is the window to make invisible. If you expect the window to be re¬ 
opened later in the program’s execution, this is the best approach since switching 
between invisible and visible is much faster than loading from disk and removing 
from memory. 

Your second alternative is to remove the window from memory using the VRDe- 
stroy function. Its syntax is: 


Okay = VRDestroy("Windowl") 


where Windowl is the window to remove from memory. VRDestroy doesn’t alter the 
contents of the program file, so you can recreate the window simply by running the 
appropriate subroutine again. All VRDestroy destroys is the window that’s loaded in 
memory. 

I took the VRDestroy approach with the Window-1 program. Like the Open sub¬ 
routine, each of the Close Window buttons issues a command like CALL Close 1 and 
handles all the closing in one subroutine. That subroutine is very similar to the Open 
subroutine, only it closes the window rather than opening it, and enables the Push- 
Button object rather than disabling it. This subroutine is: 


Close: 

Number = Arg(1) 

Window = "Window" ! ! Number 
Button = "Load_Window" ! ! Number 
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Okay = VRDestroy(Window) 

Okay = VRSet(Button, "Enabled", 1) 
return 


Now you have Window-1 in operational form; Figure 14.4 shows it running with all 
three secondary windows open. When Window-1 runs, VX-REXX automatically 
places the window in the center of the screen. As each window is opened, VX-REXX 
automatically places that window in the center of the screen. I had to move the win¬ 
dows as I opened them. 

Windowl and Window2 will move as you move the primary window because their 
MoveWithParent property is turned on. Window3 has this property turned off, so it 
doesn’t move as you move the parent. The parent is independent of the child, so if 
you move either of the three windows the parent doesn’t move. Also note that mov¬ 
ing a window affects only that version of the window. If you create Windowl, move 
it, close it, and reopen it, the new version will once again be centered on the screen. 

Positioning the Window 

As you’ve seen, VX-REXX automatically centers the primary window on the screen, 
and when the program opens a secondary window it then centers that window— 
even if that places it on top of another window. For this reason, you might want to 
control the placement of windows, especially if your program uses multiple windows. 

There are two properties to control the placement of both objects and windows: 
Left and Top. The Left property controls the positioning of the left edge of the ob- 
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Figure 14.4 Window-1 running. This version opens each window centered on the screen, so they’ve been 
moved manually. 
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ject, while the Top property controls the positioning of the top edge of the object. 
The positioning of the bottom and right edges of the object is determined by the ob¬ 
ject’s height and width and, of course, the placement of its left and top edge. 

The units for both the Left and Top property are either twips or pixels. A twip is 
/20 of a point and a point is & of an inch, so there are 72 x 20 or 1,440 twips per inch. 
The actual size is scaled automatically for screen resolution and monitor size, so this 
conversion is approximate. Of course, pixels also depend on screen resolution so po¬ 
sitioning by either method, while exact on your screen, will vary from system to sys¬ 
tem if you distribute your programs to other users. 

Naturally, the position of the window can’t be controlled until the window has 
been created. The modified Open subroutine is as follows, with line numbers added: 


1. 

2. 

3. 

4. 

5. 

6 . 
7 . 
8 . 
9. 


Open: 

Number = Arg(1) 

Window = "Window" ! I Number 
Button = "Load_Window" ! I Number 
Okay = VRLoadSecondary(Window) 

Okay = VRSet(Button, "Enabled", 0) 

Okay = VRSet(Window, "Left", Left.Number) 
Okay = VRSet(Window, "Top", Top.Number) 
return 


Compared to the original Open, lines 1-6 are the same. Lines 7-8 position the win¬ 
dow using the Left and Top properties and values in two stem variables created in 
the Init subroutine for this purpose. That portion of the Init subroutine is: 


Left.1 = 0 
Left.2 = 6200 
Left.3 = 0 
Top.1 = 0 

Top.2 =0 

Top.3 = 5760 

If you were to run the program in this form, you would see that it has a very annoy¬ 
ing problem. The windows can’t be positioned until they’re opened, so they first ap¬ 
pear in the center of the screen and then jump to their assigned positions. Not only 
is this annoying, but it looks unprofessional. 

You might think that the solution is to make each window invisible when designing 
it. That way, the window loads invisibly and you can make it visible after positioning 
it. If you try that, however, you’ll find that it doesn’t work. In fact, as soon as your in¬ 
visible windows load, they automatically become visible and continue to bounce 
around the screen! 

This is because the VRLoadSecondary function loaded the secondary windows, 
but VX-REXX has no VRLoadSecondary function! Normally you’d load a window 
with the VRLoad function, but it takes several lines of code to load a window. So VX- 
REXX automatically adds the following lines of code to your program: 


VRLoadSecondary: procedure 
name = arg( 1 ) 

window = VRLoad( VRWindow(), VRWindowPath(), name ) 
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call VRMethod window, "CenterWindow" 
call VRSet window, "Visible", 1 
call VRMethod, window, "Activate" 
return window 


So every call to VRLoadSecondary actually runs this subroutine. You can see that the 
fourth line automatically centers the window and the fifth line makes it visible. Since 
this subroutine doesn’t start with /*:VRX */, it doesn’t show up in the list of subrou¬ 
tines in the VX-REXX editor. It is, however, part of the Main subroutine. I’m told that 
the definition of VRLoadSecondary is being changed in version 2.1 to, among other 
things, make it much easier to customize the loading of secondary windows. 

There are a couple of options for handling this. You could write a similar routine 
and call it something else, or you could modify the subroutine. 

The first option is the safest, but I felt like experimenting so I selected the latter 
one. I removed the VRLoadSecondary subroutine VX-REXX had added and then I 
inserted my own VRLoadSecondary subroutine. This subroutine is as follows, with 
line numbers added: 


1. VRLoadSecondary: 

2. PROCEDURE 

3. Name = Arg(1) 

4. Left = Arg(2) 

5. Top = Arg(3) 

6. Window = VRLoad(VRWindow(), VRWindowPath(), Name) 

7. Okay = VRSet(Window, "Left", Left) 

8. Okay = VRSet(Window, "Top", Top) 

9. Okay = VRSet(Window, "Visible", 1) 

10. Okay = VRMethod(Window, "Activate") 

11. return Window 

Line 1 makes all the variables local to the subroutine. The subroutine expects to re¬ 
ceive the name of the window and the left and right coordinate for the window as ar¬ 
guments, and lines 3-5 assign these to variables. Line 6 loads the window, lines 7-8 
positions it, line 9 makes the window visible, and line 10 makes it active. 

Of course, be extremely careful when altering the code VX-REXX automatically 
adds to your programs. In most cases, you’d be better off using the first option—cre¬ 
ating your own function and naming it something else. 


Working 

In this demonstration program, we’ll create a program that manages the secondary 
window itself without the user needing to do anything. Working is a demonstration 
program that displays a “Working” message while the program performs a long se¬ 
quence of calculations. This prevents the user from thinking the program has locked 
up and trying to abort its operation. 

Figure 14.5 shows the user interface for Working. Note that the secondary window 
is fairly small. It has no title bar or buttons because you don’t want the user to close 
the window. The entire area of the window is taken up by a single Descriptive Text 
object containing the “Working” message. 
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Figure 14.5 The user interface for the Working program. Both the primary and secondary windows are 
visible. 


The large button in the primary window controls the demonstration from its Click 
event. The associated subroutine is as follows, with line numbers added: 


1. 

PB_Demo_Click: 




2. 

CALL Working 

ON 



3. 

DO I = 1 TO 10000 



4. 

TotalOl = 

Random() 

* 

Random() 

5. 

Total02 = 

Random() 

* 

Random() 

6. 

Total03 = 

Random() 

* 

Random() 

7 . 

Total04 = 

Random() 

* 

Random() 

8. 

Total05 = 

Random() 

* 

Random() 

9. 

Total06 = 

Random() 

* 

Random() 

10. 

Total07 = 

Random() 

* 

Random() 

11. 

Total08 = 

Random() 

* 

Random() 

12 . 

Total09 = 

Random() 

* 

Random() 

13 . 

TotallO = 

Random() 

* 

Random() 

14 . 

END 




15. 

CALL Working 

OFF 



16. 

return 





Line 2 calls the Working subdirectory and passes it the ON flag to activate the sec¬ 
ondary window. Lines 3—14 simulate a set of complex calculations by multiplying a 
series of random numbers together. Line 15 calls the Working subdirectory and 
passes it the OFF flag to deactivate the secondary window. Since line 2 turns the sec¬ 
ondary window on and line 15 turns it off, the secondary window is completely con¬ 
trolled by the program. 

The Working subroutine is explained in detail in Figure 14.6. I originally tried to 
make the “Working” message flash by using a Timer object to alternate the colors of 
the message. However, it didn’t generate Trigger events while the calculation simu- 
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lation was running, and so the message didn’t flash. You’ll see this program again in 
Chapter 17. 


Music-4 


Music-4 is a modified version of Music-2 that allows the user to load music files from 
disk, causing the piano to act like a player piano. As the keys in the file are played, 
they’re highlighted on the screen so the user can follow the music on the screen. 
This might help someone learning to play the piano. A second octave of keys has 
been added, as have the sharp keys. 

The first line of the music file must be the name of the song with nothing else on 
that line. The remainder of the file contains the notes, with a space, comma, or Re- 


vX-Rexx Code 

Explanation 

Working: 

The name of the subdirectory. 

PROCEDURE 

This causes all the variables in 
the subroutine to be local vari¬ 
ables. 

Flag = Arg(l) 

This stores the first argument 
passed to the subroutine to the 
Flag variable. 

IF Flag = "ON" THEN 

DO 

jflHHHfll 

Okay = VRSet("Windowl", "HintText", 
"Working...Please Wait") 

Change the hint text of the win¬ 
dow. 

Okay = VRLoadSecondary("Working") 

Load the secondary window. 

Todo = 0 

Set a flag variable to zero. This 
is used to control the visibility 
of selected objects. 

END 

1 

ELSE 

DO 

if the Flag variable does not 
equal ON, then do the follow¬ 
ing. 

Okay = VRDestroy("Working") 

Close the secondary window. 

Todo = 1 

Set a flag variable to one. This is 
used to control the visibility of 
selected objects. 

Okay = VRSet("Windowl", "HintText","Push 
Big Button To Show Demonstration") 

Reset the hint text for the win¬ 
dow. 

END 

The end of the ELSE section. 

Okay = VRSet("PB_Demo", "Enabled", Todo) 
Okay = VRSet("PB_Quit", "Enabled", Todo) 
Okay = VRSet("PB_Demo", "Visible", Todo) 
Okay = VRSet("PB_Quit", "Visible", Todo) 

Turn these buttons on or off 
depending on the setting of the 
Todo variable. The Enabled set¬ 
ting is actually redundant since 
an invisible button is by defini¬ 
tion disabled. 

return ] 

Exit the subroutine. 

Figure 14.6 The Working subdirectory of the Working program. 
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turn between notes. Only one divider between notes is allowed. Also, the notes 
must be entered in uppercase. Entering an open parenthesis, (, to a note in¬ 
creases the length of time it’s held. Multiple parentheses can be used and they can 
be placed anywhere in the note. Adding an S to the end of a note makes it sharp. 
The ! causes the song to pause for the length of one note. Tunes can be as long as 
you like. 

In order to keep the keyboard looking clean, Music-4 uses a menu to load new 
songs, play the song that’s loaded, and exit the program. These are explained in de¬ 
tail in the next chapter. 

Figure 14.7 shows the user interface. The NoteError window is a modeless win¬ 
dow that displays information on invalid notes in the file. The process begins 
when the user elects to load a music file. The program runs the Menu2_Click sub¬ 
routine: 


Menu2_Click: 

InFile = VRFileDialog("", "Load A New Tune File", "0", "*.TUN") 

IF InFile = "" THEN 
DO 

CALL Beep 500, 500 
RETURN 

END 

CALL LoadTune 
return 


If the user clicks the Cancel button, VRFileDialog will return a nul string, which is 
then stored to InFile. This routine shows how you can test on that to make sure the 
user picks a file. Here, if the user doesn’t pick a file, the program will beep and return 
to the main screen. 

If the user selects a file, this subroutine calls the LoadTune subroutine, which 
loops through the file, placing the song title in a Descriptive Text object and loading 
all the notes. It’s as follows: 


LoadTune: 

Title = Lineln(InFile) 

Okay = VRSet(DT_Title, Caption, Title) 

1 = 1 

DO WHILE Chars(InFile) > 0 
Notes.I = Charln(InFile) 

1 = 1 + 1 

END 

Okay = LineOut(InFile) /* Close File */ 
Notes.0=1 
CALL ProcessNotes 
return 


Each note is stored in the Notes stem variable. Once all the notes are loaded, the 
LoadTune subroutine calls the ProcessNotes subroutine to verify each note. This is 
performed while the song is being loaded, both to notify the user right away of any 
problems with the song and to speed up playing the song since once the notes are 
verified they can be played without any additional error-checking. The ProcessNotes 
subroutine is fully explained in Figure 14.8. 
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Figure 14.7 The Music-4 user interface. 


ProcessNotes: 


[This subroutine processes the 
musical notes to make sure there 


are no errors 


/* To Make Processing Easier 
Will Assume The Following: 

1. A Space Ends A Note 

2. A Return Ends A Note 

3. A Comma Ends A Note 

4. Notes Will Be Separated By Only One 
Divider That Is, Two Notes Will Not Be 
Separated By Both A Comma And A Return 

5. Notes Entered In Uppercase 

*/ _ 


Play.0 = 0 
Count = 1 
NoteToPlay = "" 
ToneLength = Duration 


DO I = 1 TO Notes.0 



mtializmg some variables 


-oop through ail the notes to 
est. 


Figure 14.8 The ProcessNotes subroutine of the Music-4 program. 






























204 Advanced VX-REXX Topics 


VX-kexx Code 1 

Explanation 

SELECT J 

Pick a course of action. 

WHEN (Notes.I = 'Od'x) | (Notes.I = " ")’ 
| (Notes.1 = ",") THEN 

When the next note is a divider 

character... 

IF NoteToPlay = "" THEN NOP 

If the pending note is blank, 
then do nothing. 

ELSE 

DO 

Otherwise, do the following. 

IF CheckThisNote() = 0 THEN 

DO 

If the CheckThisNote returns a 
flag indicating that this note is 
valid, then do the following. 

Button = "PB_" | NoteToPlay 

Create a variable containing the 
name of the button to push. 

Play.1.Count = Music.NoteToPlay 

Store the note to play to a stem 
variable. 

Play.2.Count = ToneLength 

Store the duration to a stem vari¬ 
able. 

Play.3.Count - Button 

Store the name of the button to 
push to a stem variable. 

Count = Count + 1 

Increase the note counter by 

one. 

END 

End of the IF CheckThisNoteQ 
= 0 loop. 

ToneLength = Duration 

Reset the duration. 

NoteToPlay = "" 

Reset the note. 

END 

End of the “Else 5 * loop. 

WHEN Notes.1 = "(" THEN ToneLength = 
ToneLength + Increase 

If the character to test is an open 
parenthesis, then increase the 
length of time the note is to 
play. 

WHEN Notes.I = "I" THEN 

DO 

Play.1.Count = 32767 

Play.2.Count = ToneLength 

Play.3.Count = "SKIP" 

Count = Count + 1 

ToneLength = Duration 

END 

When the character is a 1, then 
schedule a pause. 

WHEN Notes.I = 'Oa'x THEN NOP 

When the character is a Return, 
do nothing. 

OTHERWISE NoteToPlay=NoteToPlay||Notes.I 

If the character is not one of the 
special characters above, it must 
be a character in a note, so 
append it to the NoteToPlay 
variable. 

END 

End of the Select loop. 

END 

End of the DO 1 = 1 TO Notes.0 
loop. 

Play.O = Count - 1 

Since the count was incremented 
on the last pass through, 
decrease it by one. 

return 

Exit the subroutine. 


Figure 14.8 Continued. 
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While ProcessNotes handles setting up the stem variable that’s used to play the 
song, it calls the CheckThisNote subroutine to check each of the notes individually. 
That subroutine displays a modeless window with the error message when an invalid 
note is encountered. The CheckThisNote subroutine is as follows, with line numbers 
added: 

1. CheckThisNote: 

2. PROCEDURE EXPOSE NoteToPlay ValidNotes. ErrorWindowOpen Message 

3. DO Q = 1 TO ValidNotes.0 

4. IF NoteToPlay = ValidNotes.Q THEN RETURN 0 

5 . END 

6. IF ErrorWindowOpen = "NO" THEN 

7 . DO 

8. Okay = VRLoadSecondary("ErrorWindow") 

9. ErrorWindowOpen = "YES" 

10. END 

11. Message = Message!!.! iNoteToPlay! ! " ' Is Not A Valid Note And 

Was Skipped"!!'Od'x 

12. Okay = VRSet("DT_Error", "Caption", Message) 

13. RETURN 1 

14. return 

Line 2 makes it a procedure and exposes certain variables. Lines 3-5 loop through all 
the valid notes and compare the note in question to each one. If it matches one, the 
subroutine returns a zero to the ProcessNotes subroutine to let it know the note is 
valid. The subroutine continues past line 5 only if an invalid note is encountered. 

Line 6 checks to see if the window has been opened and, if it hasn’t, then lines 
7-10 open the window and set a flag so the program won’t try to open the window 
again. Line 11 appends a new error message onto the error message string. This al¬ 
lows multiple error messages to be displayed in one Descriptive Text object. If they 
exceed the available space, the Descriptive Text object won’t present a scroll bar, so 
part of the message is lost. Line 12 places the message into the Descriptive Text ob¬ 
ject, and line 13 returns control to the ProcessNotes subroutines and passes back a 
value to indicate the note contained an error, so ProcessNotes won’t treat it as a valid 
note. Figure 14.9 shows Music-4 running and loading ERROR.TUN, which contains 
several errors. 

Once the song has been loaded, the PlaySong subroutine plays the song. With line 
numbers added, it is: 

1. PlaySong: 

2. DO 1=1 TO Play.0 

3- IF Play.3.I \= "SKIP" THEN OldColor = VRGet(Play.3.I, BackColor) 

4- IF Play.3.I \= "SKIP" THEN Okay = VRSet(Play.3.I, BackColor, Red) 

5. CALL BEEP Play.1.I, Play.2.I 

6. CALL BEEP 32767, NotePause 

7- IF Play.3.I \= "SKIP" THEN Okay = VRSet(Play.3.I, BackColor, 

OldColor) 

8 . END 

9. return 

Line 2 loops through all the notes to be played. If the note to play isn’t a “skip” note, 
line 3 records the background color of the key while line 4 changes the background 
color to red. This allows the user to see the key that’s being played. Line 5 plays the 
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B Note Error 
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Figure 14.9 Music-4 running, loading a music file containing errors. 
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Figure 14.10 Music-4 playing music. 


note. Without a delay, Music-4 would play the notes one after another—too fast for 
the user to listen to properly. Line 6 prevents this by causing the program to pause 
for a specific time. Since REXX supports pauses only in second increments, which 
are much too long, the program simply plays a note too high for the user to hear. Line 
7 restores the background color to the key that was played and line 8 ends the loop. 
Figure 14.10 shows the program running. 

Modal Windows 

A modeless window allows the primary window to continue running and thus allows 
the user to continue to access the primary window. Clearly, with Working you want 
the primary window to continue running; otherwise, the simulated calculations 
wouldn’t be completed until the message window was closed. 
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However, there are times when you’ll want to disable the primary window while a 
secondary window is active. For example, if your program prompts for a filename to 
use for saving, you probably want the primary window to pause until it receives a 
valid name. Or if a sensitive program prompts for a password, you don’t want the 
user to have access to the primary window until a valid password is entered. When 
you want to disable the parent until the child finishes, you need a modal window. 

A modal window is stored in a file separate from the primary window. This means 
that the secondary window doesn’t have access to any of the subroutines from the 
primary window. The only variables the secondary window has access to from the 
primary window are those it receives as arguments when it’s first called. Like any 
REXX program, the secondary window can pass a single variable back to the primary 
window. 

The primary window 

As before, the first step to creating a secondary window is to design the primary win¬ 
dow. As an example for this process, we’ll create a program called Window-2. Win¬ 
dow-2 is a demonstration program that simply loads a single modal window when the 
user clicks on a PushButton object. Then this modal window displays the arguments 
passed to the modal window when it was opened. 

The Files window manages the various files during the design phase, including 
switching between the various files to edit them, deleting an existing file, and creat¬ 
ing a new one. You can create a new file by using the main Project menu, and display 
the Files window by pressing F5 or selecting it from the Windows menu. The Files 
window is automatically displayed when you create a new window file. 

Creating the modal secondary window 

You can create a new window file using the New Window File option of the main Proj¬ 
ect menu or the Files window. You can also press Ctrl-W. If the Files window isn’t vis¬ 
ible when you create this new file, it’s automatically displayed. The first new window 
file you create is named Window2, the second Window3, and so on. You can rename 
them by saving them when you first save a window file. 

When you create a new window file, it’s much like a new program file. It has the 
five subroutines automatically added to any program file: Fini, Init, Main, Quit, and 
Window_Close. Of course, the name of the last subroutine is modified to match the 
name you or VX-REXX gives the window. There is, however, no WINDOW.VRP file, 
so the window file doesn’t show up on the display when you select Open from the 
Project menu. Since it’s automatically accessible when you open the primary window 
file, there’s no need to open it. 

The new window file is stored in a separate file, so it can’t access any of the vari¬ 
ables or subroutines of the primary window. It also doesn’t share any object names 
with the primary window, so if the primary window has a PushButton object named 
PB_1, this new window file can also have a PB_1 PushButton object without conflict. 
In fact, VX-REXX will automatically begin recycling the names it automatically as¬ 
signs to objects. 
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Using the modal secondary window when the program is running 

Like the modeless secondary window, modal secondary windows aren’t loaded auto¬ 
matically by VX-REXX when the program runs. Since a modal window deactivates its 
parent while running, you wouldn’t want to load one automatically in the Init section 
and make it invisible. With a modal window, you want to display it when you need to 
get information and remove it from memory when you have the information, so the 
parent can resume execution. If you need the same information again, simply load 
the window from the disk again. The command to load a modal window is: 


Okay = Window2(VRWindow()) 


where Window2 is the name of the window to load. The VRWindow() function must 
be the first argument passed to the window. This supplies the internal name VX- 
REXX uses for the parent window. The modal window uses this to disable it and its 
other children. The modal window does this automatically, without you doing any¬ 
thing other than supplying it with the internal name of the parent window. 

You can pass multiple arguments to the modal window file by separating them 
with commas and listing them after the VRWindow function. In the modal window 
file, they’re accessed normally with the InitArgs stem variable. Interestingly, the 
value of the VRWindow function isn’t stored to the stem variable, so the InitArgs 
stem variable contains only the “real” arguments passed to the modal window file. 

Window-2 uses a SpinButton object with possible values 0-5 to control how many 
arguments are passed to the modal window file. Its Change event stores a value to 
the ToPass variable, which is initialized in the Init subroutine to a value of zero in 
case the user doesn’t change the SpinButton object. The Click event for the large 
button actually calls the modal window file. That section of the code is: 


SELECT 

WHEN ToPass = 0 THEN Get=Second(VRWindow() ) 

WHEN ToPass = 1 THEN Get=Second(VRWindow(),'First') 

WHEN ToPass = 2 THEN Get=Second(VRWindow(),'First','Second') 

WHEN ToPass = 3 THEN Get=Second(VRWindow(),'First','Second','Third') 

WHEN ToPass = 4 THEN Get=Second (VRWindow () , 'First' , 'Second' , 'Third' , 'Fourth' ) 
WHEN ToPass = 5 THEN Get=Second(VRWindow(), 'First', 'Second', 'Third', 'Fourth', 'Fifth') 


END 


This code simply calls the modal window file with a variable number of parameters 
depending on the value of the ToPass variable. The arguments are converted for dis¬ 
play in the modal window file by the SetCaption subroutine. It is as follows, with line 
numbers added: 


1. SetCaption: 

2. Return = "0d"x 

3. Caption = "" 

4. IF InitArgs.0 = 0 THEN Caption = "No Arguments Passed To Window" 

5. ELSE DO 

6. DO 1=1 To InitArgs.0 

7. Caption = Caption !! "Argument #" !! I "Is" InitArgs.I 

! ! Return 


8. 


END 
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9 . END 

10. Okay = VRSet("DT_1", "Caption", Caption) 

11. return 

Line 2 creates a variable containing a Return to use in constructing the variable. 
Since it will be used with a Descriptive Text object, only half of the “0d0a”x Return 
is used, as has been discussed before. Line 3 sets the Caption variable to null so the 
string combinations work properly. Line 4 creates a caption if no arguments were 
passed to the program. Otherwise, lines 6-8 loop through and create the caption. 
Line 10 inserts the caption into the Descriptive Text object. 


Returning a value to the primary window 

The first step to returning a value from the modal window file is to create the value 
to return. Typically, the window prompts the user for some type of information, such 
as a filename or password, and this information forms the basis of the value to return. 
It’s likely that some manipulation to put it into appropriate format is required. If more 
than one piece of information is being returned, they must be combined together be¬ 
fore they’re returned and parsed back apart in the primary window program. 

In Window-2, the user isn’t asked for any information, so that can’t form the basis 
of developing a return value. Rather, the Close Window button develops a new cap¬ 
tion for the SeeDemo button in the main program. This caption consists of a constant 
phrase and random number. The Click event for this button is: 


Quit_Click: 

ReturnCode = "Modal Window File Returned Value Of" Random() 
CALL Quit 
return 


Since the Close Window button is the only way to exit this particular modal window file, 
you don’t have to be concerned about multiple paths. However, if multiple paths exist 
to exit the window, such as Continue and Cancel buttons, you must make sure that a 
value for the variable to contain the return value (ReturnCode in this example) always 
exists. The best way to do this is to assign it an initial value in the Init subroutine. 

The next step is to modify the Fini routine to return the value to the primary win¬ 
dow. This is done by replacing the normal zero with the name of the variable con¬ 
taining the return value for the Return command in this subroutine. The modified 
Fini subroutine for this example is as follows: 


Fini : 

window = VRWindow() 
call VRSet window, "Visible", 0 
drop window 
return ReturnCode 


Closing the modal secondary window when the program is running 

Closing the window is easy. Since it’s stored in a separate file, VX-REXX handles 
most of the work for you. To close the window and return to the primary window, just 
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issue a CALL Quit command. Of course, if a value is being returned, the changes de¬ 
scribed previously must also be made. 

Using the returned value in the primary window program 

The value is returned to the primary window program like any value from a user-de¬ 
fined function. The code that calls the modal window file in Window-2 is: 


SELECT 

WHEN ToPass = 0 THEN Get=Second(VRWindow() ) 

WHEN ToPass = 1 THEN Get=Second(VRWindow(),'First') 

WHEN ToPass = 2 THEN Get=Second(VRWindow(),'First','Second') 

WHEN ToPass = 3 THEN Get=Second(VRWindow(),'First','Second','Third') 

WHEN ToPass = 4 THEN Get=Second (VRWindow () , 'First' , 'Second' , 'Third' , 'Fourth' ) 
WHEN ToPass = 5 THEN Get=Second(VRWindow(), 'First', 'Second', 'Third', 'Fourth', 'Fifth') 

END 

Since it’s called using the Get variable, that variable automatically contains the re¬ 
turned value once the modal window file returns control to the primary window file. 
The subroutine then uses that variable to change the caption of the SeeDemo but¬ 
ton. The line that does that is: 

Okay = VRSet("SeeDemo", "Caption", Get) 

Figure 14.11 shows the program running with the modal window showing, automati¬ 
cally positioned in the center of the screen. Before displaying this window, the user 
elected to show four arguments. Figure 14.12 shows the primary window again as it ap¬ 
pears after a value has been returned from the modal window. Even though the caption 
of the button has changed, if you click on it again it will run another demonstration. 


J-0 Window^ fedal Window Demonstration by Ronny Richardson j ° |D 


Modal Window by Ronni) Richardson 


Click On Close Window Butt on To Exit M oda l W indo w 

Argument 81 Is First 
Argument 82 Is Second 
Argument 83 Is Third 
Argument 84 Is Fourth 


Close Window 



Figure 1 4.1 1 The Window-2 program showing its modal window. 
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Figure 14.12 Window-2 running, showing the caption after returning from the 
modal window. 


Password 


Password is a demonstration program that asks the user for a password as soon as 
the program starts to run. The only valid password is Richardson—and capitalization 
is important. 

Once the password is entered, the program returns to the primary window where 
it displays a message that varies depending on if the correct password is entered. At 
this point, all the user can do is click on a button to exit the program. If this were an 
actual program, it might display a second window prior to exiting when an invalid 
password was entered, and return the user to the primary window if a valid password 
was entered. This would prevent the program from being used until a valid password 
was entered. 

The first step is to create the primary window. In this demonstration program, a De¬ 
scriptive Text object displays the results of asking for the password and there’s a Push- 
Button object that the user can click on to exit the program after entering the password. 

If this were a production software package containing sensitive information, you 
might want to load the primary window with all the objects invisible since the screen 
is momentarily visible before it’s covered by the password screen. That way, the user 
couldn’t see the contents of the program until a valid password was entered. 

The next step is to create the modal window to get the password. There’s an Entry- 
Field object to get the password, a Descriptive Text object to display a message, and 
two PushButton objects for when the user is finished. The EntryField object is config¬ 
ured in its property notebook to mask the text so the text the user enters isn’t shown 
on the screen. That prevents someone from seeing the password as the user enters it. 

This window is configured to return one of three values: -1 if the user selects the 
Cancel button, 0 if a valid password is entered, and 1 if the user makes three at- 
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tempts and fails to enter a valid password. The Click event for the Cancel button is 
as follows: 


Cancel_Click: 

ReturnCode = -1 
CALL Quit 
return 


Of course, the Fini subroutine has been modified, as described previously, to return 
the contents of the ReturnCode variable to the primary window The Click event for 
the OK button calls the OK subroutine. That subroutine is as follows, with line num¬ 
bers added: 

1. OK: 

2. Count = Count + 1 

3. Password = VRGet("EnterPassword", "Value") 

4. IF Password = ValidPassword THEN 

5 . DO 

6. ReturnCode = 0 

7. CALL Quit 

8 . END 

9. ELSE IF Count = 3 THEN 

10. DO 

11. ReturnCode = 1 

12. CALL Quit 

13. END 

14. ELSE 

15. DO 

16. CALL Beep 500, 500 

17. Okay = VRSet("EnterPassword", "Value", "") 

18. END 

19. return 

Line 2 increments the counter that’s used to count the number of password at¬ 
tempts. It’s initialized to zero in the Init section. Line 3 reads the password from the 
Entry Field object. The valid password is stored in the ValidPassword variable, so if 
the user enters a valid password lines 4-8 set the return code to 0 and exit the win¬ 
dow. The program reaches line 9 only if an invalid password is entered. If the num¬ 
ber of attempts has reached three, lines 9-13 set the return code to 1 and exit the 
program. Otherwise, the user has at least one more attempt so lines 14-18 beep the 
speaker, clear out the contents of the EntryField object, and allow the user to con¬ 
tinue by not exiting the window. 

In the primary window, the Init subroutine first loads the modal window to make sure 
it’s executed right away and then changes the caption of the Descriptive Text object de¬ 
pending on the results of the modal window. Here is that section of the Init subroutine: 


Valid = GetPassW(VRWindow()) 

IF Valid = -1 THEN Okay=VRSet("Message","Caption","You Pressed Cancel 
For Password") 

IF Valid = 0 THEN Okay=VRSet("Message","Caption","You Entered A Valid 

Password") 

IF Valid = 1 THEN Okay=VRSet("Message","Caption","You Tried 3 Times 

But Missed Password") 

Okay = VRSet("Quit", "Visible", 1) 
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A few comments about passwords 

You have two choices on how to store your passwords: you can hardwire them into 
the program as I did previously or you can read them from a file. Both methods have 
advantages and drawbacks. If you store them in the file, it’s much harder for the user 
to find them because they’re encrypted into the .EXE file. However, that makes it 
impossible for users to change their passwords without access to the source code 
and a copy of VX-REXX. 

You might think this method makes it impossible for anyone to read the password, 
but unfortunately it’s not. VX-REXX keeps both the encrypted source code and a to- 
kenized version of your program in the .EXE file. Since the tokenized version is un¬ 
readable in the traditional sense, it’s not encrypted. However, the tokenized version 
sometimes leaves variable definitions in a readable form when the .EXE file is 
viewed, so this method shouldn’t be considered secure. I’ve reported the problem to 
Watcom and they’re looking at changing it in a future release. 

If you store the password in a file, you can write a program or add a window to give 
the user the option of changing the password. You would then store the new value to 
the file. However, this means that the password exists in a file so someone looking to 
find the password has a better chance of finding it. You can use the REXX string-ma¬ 
nipulation facilities to encrypt the password before writing it to the file and decrypt 
it after reading it from the file. This is the best approach if you’re worried about se¬ 
curity rather than just trying to stop a curious user. 


Summary 

This chapter discusses how to add support for multiple windows to your programs. 
Additional windows can be either modeless or modal. A modeless window has its 
code stored in the same file as the first window. A modeless window can share sub¬ 
routines and variables with the primary window and doesn’t disable the primary win¬ 
dow when it runs. This allows the user to switch between windows. A modal window 
is stored in a separate file so it cannot share subroutines or variables with the win¬ 
dow that activated it. When a modal window is activated, it automatically disables 
the window that called it plus any children that window has created. The chapter 
also discusses the advantages and disadvantages of storing a password in an .EXE 
file versus a data file. 

The Window-1 program shows how to add multiple modeless windows to a pro¬ 
gram. Working shows how to use a single modeless window to assure the user that 
the program is working while it performs some long series of calculations. Window-2 
shows how to add a single modal window to a program, send values to it, and receive 
values from it. Password shows how to add password protection to a program. 
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Menus 


With the programs developed so far, you’ve placed buttons or other objects on the 
screen to initiate every action you wanted the program to execute. When a program 
has only a few actions, this works well and makes designing and using the program 
fairly easy. However, when the program has a lot of different actions it needs to exe¬ 
cute, this method can lead to a very cluttered screen. To see this, just look back at 
the Function program running in Figure 12.1. 

Most software doesn’t initiate actions using items on the screen. Rather, you in¬ 
teract with the software through its menus. VX-REXX has the ability to add very de¬ 
tailed menus to its programs and these menus can initiate any action, just like the 
objects on the screen. This chapter will describe how to construct VX-REXX menus. 

As part of this discussion, we’ll add a simple menu to a program called Menu. The 
Menu program is a demonstration program that will let you change the color and 
caption of a Descriptive Text object. The user interface for the Menu program con¬ 
sists of a PushButton object for exiting the program and the Descriptive Text object 
that will be modified by the menu. 

The Menu Bar 

A typical application has a menu bar across the top of the screen. A menu bar is a 
strip of menus running horizontally across the top of the application. The menu bar 
for Describe, an OS/2 word processor, is shown in Figure 15.1. Most of the entries in 
a menu bar aren’t actual menu items. Rather, they trigger the display of a pull-down 
menu. A pull-down menu is displayed directly below or beside the entry in the menu 


File Edit View Words Style Frames Utilities Options Window Help 


Figure 15.1 The DeSeribe menu bar. 
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bar and contains additional menu selections. Figure 15.2 shows the DeScribe pull¬ 
down menu for the File entry in its menu bar. 

To access a pull-down menu, you first use the mouse to click on the applicable 
menu-bar entry. That automatically displays its associated pull-down menu. You can 
then click on the desired item using the mouse. Note that for each menu option in 
Figure 15.2, a single letter is underlined. This is called a mnemonic . Once the pull¬ 
down menu is displayed, you can press this underlined letter rather than using the 
mouse to select that menu option. 

If you look back at Figure 15.1, you’ll see that the DeScribe menu bar has mnemon¬ 
ics. You can use these to select a menu item from the menu bar without using the 
mouse. Do this by holding down the Alt key while pressing the mnemonic letter. 

For each menu, the mnemonic key for each menu item must be unique. If a menu 
has both a File and a Frames option, as DeScribe has on its main menu, they can’t 
both use the F as the mnemonic. If they did, only the first menu option would be ac¬ 
cessed. That’s why DeScribe uses the r in Frames as the mnemonic for this menu op¬ 
tion. In VX-REXX, the menu mnemonics are under the programmer’s control, so you 
need to be sure that each menu item in a menu has a unique mnemonic. Of course, 
different menus can use the same mnemonics. Thus, in DeScribe, the Print option in 
the File menu and the Paste option in the Edit menu can both use P as their 
mnemonic because they aren’t in the same menu. 

Look back at Figure 15.2 and you’ll see that the Open option in the DeScribe File 
menu has a Ctrl+O beside it. This indicates that holding down the Ctrl key and press¬ 
ing the 0 key is a quick way of opening a file, also called an accelerator. An acceler¬ 
ator is a keystroke combination that executes a common menu option without 
requiring you to go through the menu. Thus, Ctrl-0 works to open a file in DeScribe 
without the menu. You might also recall that you can quickly save a file in the OS/2 
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Enhanced Editor by pressing F2. When you define an accelerator for a VX-REXX 
menu item, it’s automatically added to the menu by VX-REXX. 

A Cascaded Menu 

The main menu, or menu bar, is the first level of a menu. The pull-down menu is the 
second level. When a third level is needed, it becomes a cascaded menu. A cascaded 
menu is a menu that drops down when an item from a second-level menu is selected. 
Cascaded menus are generally used when you want to shorten the second-level 
menu by grouping similar choices at a third level. When a second-level menu option 
has an associated cascaded menu, it’s usually indicated by an arrow beside its name. 

There are two types of cascaded menus: unconditional cascaded menus and con¬ 
ditional cascaded menus. An unconditional cascaded menu automatically appears 
when its second-level menu option is selected. This is indicated by a two-dimensional 
arrow in the second-level menu. A conditional cascaded menu contains one option 
that’s configured as the default option, so the menu doesn’t automatically appear. To 
reach the cascaded menu you must click on the arrow. Otherwise, the default option 
executes. This is indicated by a three-dimensional arrow in the second-level menu. 

A Pop-Up Menu 

k pop-up menu is attached to an object on the screen rather than being attached to 
the menu bar. For example, Describe uses a pop-up menu to display style sheets in 
a document. In VX-REXX, pop-up menus are attached to objects on the screen and 
pop up either when you click on that object with the right mouse button or when that 
object has focus and you press Shift-FlO. VX-REXX requires that pop-up menus be 
attached to the menu bar, but you can make them invisible so they don’t show up as 
part of the menu. 

Menu Conventions 

Some of your menu items will have more than one word in them, such as Save as..., 
Printer setup..., Stationary manager..., Master document, and Exit DeScribe, as 
shown in the DeScribe File menu in Figure 15.2. By convention, only the first word 
of each menu item is capitalized. Exit DeScribe is an exception to this only because 
DeScribe is a proper name and is always capitalized. 

Note that in Figure 15.2 some of the DeScribe menu options, such as Open... and 
Save as..., have an ellipsis after their name. This indicates that the menu option 
doesn’t execute right away but rather brings up a dialog box for you to complete. 

Other menu items in Figure 15.2, such as New and Recall, have a right-pointing ar¬ 
row beside them. This indicates that selecting this menu option brings up yet an¬ 
other menu, a cascaded menu. The final menu selection is made in this cascaded 
menu. The arrow is automatically added by VX-REXX for cascaded menus. Finally, 
Figure 15.2 shows that the DeScribe File menu has a series of lines in it. These group 
the menu into logical sets. 
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Menus in VX-REXX 

Like everything else in VX-REXX, menus are constructed of objects, only the objects 
are added with the Menu Editor rather than being drawn on the screen. The Menu 
Editor is shown in Figure 15.3. The menu bar is a MenuBar object. The MenuBar ob¬ 
ject contains Menu objects, each of which represents one of the menu items you see 
in the main menu. Each menu item contains Menultem objects, which represent the 
pull-down menu items. A menu item might also contain other menu items if it has a 
cascaded menu. 

Like other VX-REXX objects, the properties of each of these menu objects can be 
modified with the VRSet and VRGet VX-REXX functions while the program is run¬ 
ning. This allows you to alter the menu to fit the dynamics of program execution. For 
example, until data has been modified you might make the menu option for saving 
the data inactivate. 

Menu Editor 

The Menu Editor was shown in Figure 15.3. It has a number of entry fields that you 
complete to create menu items. Each entry field is as follows: 

Caption. This is the name to appear in the menu. A tilde (~) is used before the let¬ 
ter that’s to be the mnemonic for this entry. 

Name. This is the name of the object. Like other VX-REXX objects, the name must 
be unique to the program and must not contain any spaces. 
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Figure 15.3 The VX-REXX Menu Editor. 
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TABLE 15.1 Accelerator Keystrokes 


Keystroke 

Equivalent 

Keystroke 

Equivalent 

{Alt} 

Alt key 

{Backspace} 

Backspace key 

{Backtab} 

Shift-Tab 

{Ctrl} 

Control key 

{Del) 

Delete key 

{Down} 

Down arrow 

{End} 

End key 

{Enter} 

Pressing Enter or Return 

{Esc} 

Escape 

(Fl) 

Fl function key 

(F2) 

F2 function key 

<F3) 

F3 function key 

(F4) 

F4 function key 

(F5) 

F5 function key 

(F6) 

F6 function key 

{F7} 

F7 function key 

{F8) 

F8 function key 

{F9} 

F9 function key 

(F10) 

F10 function key 

{Fll} 

Fll function key 

(F12) 

F12 function key 

{Home} 

Home key 

(Ins) 

Insert key 

{Left} 

Left arrow 

(Newline) 

Shift-Enter 

{PgDown} 

Page Down 

(PgUp) 

Page Up 

{Right} 

Right arrow 

(Shift) 

Shift key 

{Tab} 

Tab key 

(Up) 

Up arrow 




Level. This is the menu level for this item. A level-1 item is on the menu bar, a level- 
2 item is a pull-down menu, and a level-3 item is a cascaded menu. VX-REXX allows 
you to go up to level 5, but this isn’t recommended except for very complex menu 
structures. 

Accelerator. This is the keystroke combination you can use to run this menu option 
without accessing the menu. This must be unique across the entire menu structure 
and you generally have accelerators defined for only the most common menu items, 
such as Save or Open. Table 15.1 lists the valid keystrokes for this field. 

Enabled. Like any VX-REXX object, a menu object must be enabled before it can be 
executed. 

Checked. This controls if a checkmark appears beside a menu entry. As a general 
rule, checkmarks are used to mark the default menu entry in a conditional cascaded 
menu. 

Visible. Like any VX-REXX object, a menu object must be visible before it can be 
executed. 


HintText This is the text that’s displayed below the title bar when this entry is high¬ 
lighted. HintText is discussed in Chapter 16. 
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HeipTag. This controls help for the menu entry. Help is discussed in Chapter 16. 

HelpText. This is the help text for the menu entry. Help is discussed in Chapter 16. 

UserData. This is arbitrary program-defined data. It isn’t used by VX-REXX. 

Defaultftem. This contains the name of the default item for a conditional cascaded 
menu. If the item is blank, the cascaded menu is an unconditional cascaded menu. 

As you can see in Figure 15.3, there’s a large area on the right of the Menu Editor 
where you see the menu code for the menu you’re constructing. There are buttons 
at the bottom to change the menu using the entered data, insert a menu item, delete 
a menu item, edit a menu event, and close the editor. There are also four arrows for 
moving menu items up or down and changing their level. 

Creating a Menu 

The best way to learn to use the Menu Editor is to use it to construct a menu for a 
program, so we’ll add a menu to the Menu program. The menu bar will contain the 
following items: 

Foreground. This will change the foreground color of the Descriptive Text object. 

Background. This will change the background color of the Descriptive Text object. 

Caption. This will change the caption of the Descriptive Text object. 

Reset. This will reset the foreground, background, and caption of the Descriptive 
Text object to its starting value. Ctrl-R will be the accelerator for Reset. 

About This will display a brief message about the program. Ctrl-A will be the accel¬ 
erator for About. This option will load a secondary window to display the information. 

Exit. This will immediately exit the program. Alt-X will be the accelerator for Exit. 
I tend to use Alt-X as the accelerator for Exit in all my menus, even when I call it 
Quit rather than Exit. 

The menu options will be arranged in the menu in the order shown. Since each of 
these options begins with a different letter, the first letter will be the mnemonic. 

Laying out the main level 

There are any number of approaches to designing a menu. I generally outline its 
structure on paper first. I then insert the first level. After that, I insert the second level 
for each of these menu items. When I use a third level, I go back and add those last. 

Figure 15.4 shows the Menu Editor with the first menu option being entered. Fig¬ 
ure 15.5 shows the Menu Editor after the menu bar has been entered. If you wanted 
to rearrange the menu items at this point, you could use the up and down arrows at 
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Figure 15.4 Entering the first menu item for the Menu program. 
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Figure 15.5 The finished first-level menu for the Menu program. 
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the bottom right of the screen to move the highlighted menu entry to a new location. 
At this point, if you close the Menu Editor and return to the program, you can see the 
menu has been added to the top of the program. This is shown in Figure 15.6 after 
the program was widened to allow for the long menu. 


Entering the second level 

The Menu Editor doesn’t have a way to insert a blank entry into the field for you to 
insert new entries. Rather, you must modify an existing entry and click on the Insert 
button to insert the modified menu item back as a new item. While it’s confusing at 
first, you’ll soon get used to it. If you want to work a little more safely, insert a sec¬ 
ond unmodified copy of a menu item and then modify that version. You will, however, 
have to modify its name because duplicates aren’t allowed. Figure 15.7 shows the 
Menu Editor with the menu finished. If this menu had a third, fourth, or fifth level, 
they would be added in the same fashion. 


Programming the menu options 

When you double-click on a menu entry over in the display area of the Menu Editor, 
it brings up the VX-REXX editor. From here, you edit the code as you would any 
other code in VX-REXX. Figure 15.8 shows the finished version of Menu running 
with its menu displayed. 


Creating a Pop-Up Menu 

Any menu on your MenuBar object can be displayed as a pop-up menu. All pop¬ 
up menus must be on the MenuBar object, but they can be hidden if you want to 
use them only as a pop-up menu. A pop-up menu is displayed when the user clicks 
with the right mouse button on an object or when the object has focus and the 


Menu by Ronny Richardson 




I Foreground Backgroun d Caption Reset About Exit | 
Click Here To End Demonstration J 

Change My Message With The Menu 







Quits 


Figure 15.6 The Menu program running. Note the menu at the top of 
the program. 
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Figure 15.7 The menu for the Menu program, with the second-level menus finished. 



user presses Shift-FlO. With either of these actions, the object generates a Con- 
textMenu event and this event displays the pop-up menu. Since the menus on the 
MenuBar object already have code associated with them, all that’s required in the 
ContextMenu event is the code to display the menu as a pop-up. The code to do 
that is: 


Okay = VRMethod( "menu", "Popup") 
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where menu is the name of the menu to be displayed as a pop-up. In the Menu pro¬ 
gram, I attached the Captions menu (ChangeCaption) as the pop-up menu for the 
Descriptive Text object. Its ContextMenu code is as follows: 


Message_ContextMenu: 

Okay = VRMethod("ChangeCaption", "Popup") 
return 

Figure 15.9 shows Menu running with the pop-up menu displayed. 


Fun-2 


Fun-2 is a modified version of the Function program that uses menus to access VX- 
REXX function descriptions rather than PushButton objects. Take a look at the 
Function program from Chapter 12. It uses 33 PushButton objects to show informa¬ 
tion on the various VX-REXX functions. Add the Quit button and you have a very 
cluttered display! A menu is the perfect way to clear up the screen clutter. 

Menus offer an additional advantage. Due to the clutter from just one set of Push- 
Button objects, there’s no room to categorize the functions or access them in differ¬ 
ent ways. Since menus take up less room and are shown only as you use them, Fun-2 
will allow you to access information in the same fashion as Function, plus it will offer 
a categorized list and a listing by function name. 

Figure 15.10 shows Fun-2 running with a menu displayed. Note that the 33 menu 
items extend all the way to the bottom of the screen. If there was one more item on 
the menu, it would be too long for the screen! Naturally, most of your menus will be 
shorter than this. 

Fun-2 won’t run on a VGA display. Fun2-VGA is a modified version, however, 
where the menus are rearranged to be shorter and fit on a VGA screen. Even users 
with higher-resolution screens might prefer this version. 
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Figure 15.9 The Menu program, with its pop-up menu displayed. 
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, VXREXX Function Information by Ronny Richardson 


| Alphabetical listing 

i .VRChAttr^ . 

VRChDir 

VRChDrive 

VRCopyFile 

VRCreate 

VRCreateFile 

VRCreateStem 

VRCurrDir 

VRCurrDrive 

VRDeleteFile 

VRDeUni 

VRDestroy 

VRDir 

VRDisklnfo 

[ VRDiskLabei 
VRExpandFIleName 
VRFileDate 
VRFiTeExist 
VRFindFile 
VRGetFileType 
VRGetini 
VRIsDir 

VRListFileType 

VRMkDir 

VROptions 

VRParseFIleName 

VRParseFilePath 

VRPrintDiaiog 

VRPrintFIle 

VRRenameFile 

VRRmDir 

VRSetlni 

VRSortStem 


Categorical Listing Functional listing About Exit 




ing properties stored in a stem 


(Parent, ObjectType, Stem) 

bf the parent object handle. A null string is used when there is no parent, 
ipe of object to create. 'Stem' is the REXX stem variable that contains the 
1st contain the property count. Stem.i contains the first property, Stem.2 
bm.3 contains the second property, Stem.4 contains it value, and so on. Note that 
half the number of stem variables used. 


iGraw-Hlll 


Figure 15.10 Fun-2 running. Note how long the menu is. The menu font is controlled globally by OS/2, so 
users with a larger menu font might be unable to see the longer menus. 


Todo-4 


Todo-4 is a modified version of Todo-3 where all the on-screen buttons have been re¬ 
placed with a menu. It has also been modified to display a pop-up screen telling 
about the program when that option is selected from the menu. 

At first, I had expected a quick conversion from the PushButton objects to the 
menu. Unlike Function, Todo-3 has only a few buttons. It has 12 copies of the Done 
and Erase buttons, and one each of the Add Todo Item, Save Date, Quit Program, 
Scroll Forwards, Scroll Backwards, and Print List buttons. So if you count the 12 
Done and Erase buttons as one of each, there are only eight buttons. 

However, the conversion ended up being harder than I had anticipated. The first 
problem was that Todo-3 determines which to-do item to either erase or remove to 
the “done” file by figuring out which Erase or Done PushButton object was clicked 
on. I added GotFocus events to each EntryField event to store its number to a vari¬ 
able, and LostFocus events to reset this variable to zero. My thinking was that I 
would require the user to click on the EntryField to delete or move to done file be¬ 
fore selecting Erase or Done from the menu. 

However, that resulted in another problem. Clicking on the menu causes the En¬ 
tryField objects to lose focus, so the variable was always reset before the Erase or 
Done menu option could process it. I solved that by deleting all the LostFocus events 
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and just having the program assume that users want to work on the last entry choked 
on when they select Erase or Done from the menu. 

That led to another problem. When the user selects Erase or Done from the menu 
before clicking on an EntryField object, none of the GotFocus events have occurred, 
so the tracking variable hasn’t been created. I corrected this by initializing it in the 
Init subroutine to assume that users want to work on the first entry if they go 
straight to the menu. 

Once I corrected these problems, the conversion went very fast. I added a menu 
option to tell about the program, which displayed another window with information 
about the program. I also eliminated the Descriptive Text object used to display the 
“Modified” message when the data had been modified since it was last saved. In its 
place, I had the Save Data menu option disabled until the data was modified. With 
that visual clue, I felt the additional text was redundant. 

After the menu was finished, I decided to make the Todo Items menu a pop-up 
menu for each of the EntryField objects. At first, that caused a minor problem be¬ 
cause clicking on an object with the right mouse button doesn’t trigger the GotFocus 
event, so the last EntryField is worked on by the Erase or Send to Done File options 
rather than the one the user clicks on. I altered the ContextMenu event to give that 
EntryField object focus, which corrected the problem. 

Figure 15.11 shows the new user interface. As you can see, removing the buttons 
left a good deal of screen blank. I chose to make the window smaller. You might want 
to expand the window to its original size and add additional to-do items instead. 
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Figure 15.11 The Todo-4 user interface. Note how much cleaner the screen looks without all the buttons. 
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Summary 


This chapter has shown you how to add “regular” menus to the top of applications 
and attach pop-up menus to any object on the screen. The Menu program is a 
demonstration program that shows these techniques. Both Function and Todo-3 
were modified to take advantage of the menus. Several other programs that have 
been covered so far would benefit from the addition of a menu. 




Chapter 

16 

Using Help and Hints 


VX-REXX supports two type of enhancements to your programs to help users: help 
and hints. This chapter will look at both of these. 


Help 

Next to well-crafted written documentation, the best thing you can do for your users 
is to add help to your programs. Help is information that pops up when the user 
presses the FI key. It explains how to do something, gives more details on a question 
or prompt the program is displaying, explains what a menu item or button does, or 
otherwise explains the use of the program. 

Not all programs need help. A program you’ve written for your own use or a pro¬ 
gram designed to fill a very specialized role is unlikely to benefit from help. However, 
most types of programs benefit greatly from help. 

VX-REXX supports three different types of help: IPF files, attaching help text to 
the HelpText property, and ASCII files. We’ll look at each of these. 

IPF help files 

IPF (Information Presentation Facility) is a tag-based language, based on the Stan¬ 
dardized General Markup Language, or SGML. This is a fairly old technology, first 
used with punch cards. Tag-based means that the source code (the help text itself) 
is written in ASCII, and formatting codes (shades of Wordstar) are embedded in the 
text. The IPF compiler handles the word wrap, font changes, and other formatting. 
The text is definitely not what-you-see-is-what-you-get. The only way to really visu¬ 
alize what your text will look like is to compile it and look at it. 

For example, the end of a paragraph isn’t denoted by a carriage return as it is in 
almost every word processor. Instead, the beginning of the next paragraph is de¬ 
noted by the paragraph tag :p. Everything between paragraph marks is treated as 
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one paragraph—if you enter it the way the text appears in the book, in long streams, 
or if you: 

enter it like this 
text, in short bursts. 

It doesn’t matter. 

Until the IPF compiler encounters a new paragraph marker, it’s all one paragraph 
and is displayed as such. To construct an IPF, you begin by constructing your ASCII 
file, including the embedded codes. A few of the more common codes are: 

:UserDoc. This marks the beginning of the document. 

:EUserDoc. This marks the end of the document. 

:Title. This is the title. The period at the end of the code is followed by a title. 

This is a comment. The remainder of the line is ignored. 

:p. This marks the beginning of a paragraph. 

:h1 res=#. This is a first-level heading. The period is followed by the heading title. 
The # is a unique number that will be referenced by VX-REXX. 

:h2 res=#. This is a second-level heading, constructed just like a first-level heading. 

: Lines. This starts a series of lines that should be displayed as lines rather than com¬ 
bined into a paragraph. 

:ELines. This ends a line listing. 

You can see the ASCII listing for TODO-5.IFP at the end of this chapter, following 
the summary. 

Once you have an ASCII file with the correct tags, it’s compiled into a binary file by 
the IPF compiler. The IPF compiler is part of the OS/2 Toolkit and so isn’t included 
with VX-REXX. If you’re planning on producing commercial applications, this is a 
valuable investment. 

The first step to using IPF help is to, of course, create the help file itself. I’ve cre¬ 
ated a version for Todo-4; we’ll attach it to the program and change the name to 
Todo-5. This is the only change we’ll make to the program. Both the ASCII and the 
compiled binary versions of the help are included on the CD-ROM. 

The second step is to attach the binary help file to the program. The easiest way 
to do this is in the property note for the main window, as Figure 16.1 shows. The 
HelpFile entry is the name of the binary help file. You can specify a full path to the 
file, but I don’t recommend this unless you know for sure where your program is to 
be installed on the hard disk. If you don’t specify a path to the file—instead give only 
the name as I did in Figure 16.1—then the file must be either in the current subdi¬ 
rectory or in one of the paths in the Help environmental variable. 
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Figure 16.1 Attaching the 
T0D0.5.HLP file to Todo-5 using 
the property notebook for the 
main Window object. 


HelpTag is the number in the ASCII file for the section to be displayed when the 
user requests help for this object. The numbers must be unique but are otherwise 
meaningless. The 1500 means that section 1500 in the help file will be displayed for 
the window. (In case you’re wondering, the only reason I started the numbers at 1500 
was because the sample I used as a guide started numbering at 1500.) HelpText isn’t 
used for IPF files, and HelpHtle is the main title to be displayed for the help window. 

Like most properties in VX-REXX, you can add this information using code rather 
than the property notebook. The code might look like this: 


Okay = VRSet("Windowl", "HelpFile", "TODO-5.HLP") 

Okay = VRSet("Windowl", "HelpTitle", "Todo Help") 

Okay = VRSet("Windowl", "HelpTag", 1500) 

Of course, the help screen pops up whenever the user presses FI. Once you attach 
the help file, you must attach help tags to every object for which you want help avail¬ 
able. You can do this with the property notebook for each object, as Figure 16.2 
shows for a RadioButton object, with the Menu Editor, or using code, as shown here: 


SetHelp: 

DO I = 1 TO 12 

GroupBox = "GB_" ! ! I 
Low = "RB_Low_" ! ! I 
Medium = "RB_Medium_" ! ! I 

High = "RB_High_" ! ! I 
Enter = "EF_" ! ! I 

Okay = VRSet(GroupBox, "HelpTag", 1501) 
Okay = VRSet(Low, "HelpTag", 1501) 

Okay = VRSet(Medium, "HelpTag", 1501) 
Okay = VRSet(High, "HelpTag", 1501) 

Okay = VRSet(Enter, "HelpTag", 1502) 

return 


I chose to attach the help tags using code for the priority RadioButton objects and 
to-do EntryField objects because there were so many. 
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Figure 16.2 Attaching a help tag 
to a RadioButton object. 


Once the help system is finished, the user can get help simply by pressing FI, as 
Figure 16.3 shows. VX-REXX and OS/2 handle the help file and even include such 
services as programmer-defined hypertext links and moving between sections. Fig¬ 
ure 16.4 shows getting a table of contents for the Todo-5 help file. Other than mark¬ 
ing the headers, nothing was done to support this. 

I’m convinced that, for the vast majority of programs, creating an IPF help file is the 
best approach. However, not everyone has an IPF compiler or wants to take the time 
to create a well-crafted IPF help file. Those people can still use help with VX-REXX 
either by attaching the help text to the HelpText property or using an ASCII file. 


Property approach 

Each VX-REXX object has a HelpText property. When text is assigned to this prop¬ 
erty, VX-REXX automatically displays it in a help window when the user presses FI 
while that object has focus. When you create help this way, VX-REXX doesn’t sup¬ 
port moving between help sections or creating hypertext links, but otherwise the 
help appears the same as with an IPF help file. 

By way of illustrating this approach, we’ll use a modified version of Viewlcn2 
called Viewlcn3. Viewlcn3 has several important modifications: 

■ The scrolling and quit buttons have been replaced by a menu. 

H Due to the extra space on the menu bar, an option has been added to change the 
drive Viewlcn3 uses to search for icons. 

■ Since Viewlcn3 allows the user to look on alternative drives, it also allows the user 
to specify the drive letter to use on the command line after the program name. The 
drive can be specified with or without the colon. 

H An option has been added to display information about the program. 

These are all fairly minor changes, so the coding isn’t explained here. You can review 
the source code on the CD-ROM that comes with this book. 
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Todo is a demonstration program for maintaining a 
todo list. It is included with the OS/2 VX-REXX 
Programming book by Ronny Richardson. 

Todo stores a priority (1=high 2=medium 3=low) code 
and an brief description of the todo item. The data 
is stored in a simple ASCII file of the format: 


Priority «1 
Description #1 
Priority «2 
Description #2 
Priority J13 
Description ft 3 
and so on 

Todo items are sorted into priority order before they 
are saved. Within each priority, items are sorted into 
alphabetical order. 
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Figure 16.3 The main help screen for Todo-5. 
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Figure 16.4 OS/2 and VX-REXX automatically add support for help-file extensions like this table of 
contents. 
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You must assign text to each item. There are two ways to do this. You can enter the 
text directly into the property notebook for that object. When entered this way, the 
HelpTag property isn’t filled in because no help file is being used. 

Entering the text directly into the property notebook has two drawbacks, how¬ 
ever. It’s difficult to enter and review long text and you can’t enter a return (“0d0a”x) 
in the text. Creating a variable and assigning it to HelpText property avoids both 
problems. Shown here is the Init section, where the help text for the main window is 
created: 


Init : 


window = VRWindow() 

call VRMethod window, "CenterWindow" 
call VRSet window, "Visible", 1 
call VRMethod window, "Activate" 
drop window 

CALL RxFuncAdd 'SysLoadFuncs', 1 RexxUtil' 

CALL SysLoadFuncs 
CALL InitialDrive 
CALL GetAllIcons 
FirstShow = 1 
CALL Showlcons 
CALL Keys 
MainHelp = 


1 SysLoadFuncs' 


Icon Viewer by Ronny Richardson" 


MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 

MainHelp 


MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
MainHelp 
: MainHelp 


" 0d0a"x 


Okay 

return 


VRSet("Windowl" 


"0d0a"x !! "0d0a"x 

" This program searches through your" 

"entire hard disk for icons. " 

"Each icon it finds is displayed on the screen. 
"If it finds more icons than " 

"can be displayed on one screen (144 icons) " 
"then the program allows " 

"you to scroll through the icons one screen " 
"at-a-time. If you wish to " 

"change drives, then use the 'Change drive' 
"option from the menu or " 

"press Ctrl-Drive where Drive is the drive 
"you wish to search for icons on." 

"HelpText", MainHelp) 


The lines below the CALL Keys line create the help text and assign it to the HelpText 
property of the main window. As you can see, it’s easier to review the help text when 
you can see it all at once, as you can here, rather than entering it in the property 
notebook. 

Figure 16.5 shows the main help screen for Viewlcn3. It appears identical to the 
help screen for an IPF file, except for the lack of a menu with the Services, Options, 
and Help items. 

You can partially compensate for the lack of features by adding a help menu item 
to your program. This menu item allows users to quickly see a particular help topic 
and rapidly switch between topics. They don’t have to close one help screen before 
requesting another. When the second is requested, if the first is still open VX-REXX 
simply replaces the text in it with the new help text. 
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This area shows the icons the program has found on your hard disk. Click on the icon of interest to see its name. 
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Icon Viewer by Ronny Richardson 


This program searches through your entire 
hard disk for icons. Each icon it finds is displayed 
on the screen. If it finds more icons than can be 
displayed on one screen (144 icons) then the 
program allows you to scroll through the icons 
one screen at-a-time. If you wish to change 
drives, then use the 'Change drive' option from the 
menu or press Ctrl-Drive where Drive is the drive 
you v/ish to search for icons on. 


Figure 16.5 Help displayed using text assigned to the HelpText property appears normal, but doesn’t al¬ 
low hypertext links or moving between sections. 


You construct the help menu just like any other menu item—even assigning help 
and hints to it. For its code, simply invoke the InvokeHelp method. The code from 
the help menu that shows the main help screen is as follows: 


MenuHelpWindowl_Click: 

Okay = VRMethod("Windowl", "InvokeHelp") 
return 


As you can see, the code to add a help option to your menu is fairly brief. 


ASCII files 

Placing the text directly or indirectly into the HelpText property works when the 
text is fairly short, but when you want to use a longer, more informative screen, this 
method can be cumbersome. To avoid the problem, VX-REXX allows you to place 
your text in an ASCII file and assign that ASCII file as the HelpText text. To illustrate 
this, we’ll add help to Music-4, also changing the name to Music-5. 

Naturally, the first step is to create the ASCII files. For Music-5, we’ll use only two. 
PIANO.TXT will appear for each object on the main screen, while ERROR.TXT will 
appear for each object on the error screen. PIANO.TXT is shown in full at the end of 
this chapter and ERROR.TXT is very similar, 
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You must be careful when you create the ASCII file. Each paragraph must be one 
long line without a Return. Some programs, such as DeScribe and the OS/2 En¬ 
hanced Editor, limit the length of a single line and will force a new line after a given 
length. When this happens, your help text starts a new line at an unnatural point in 
the file. The only solution is to either use an editor that doesn’t have this limitation 
or keep your paragraphs to a reasonable length. Because help text is shown in a nar¬ 
row window, the latter is probably the best solution. 

Once the file is ready, you’re ready to assign it to the HelpText property. Just as 
before, there are two ways to do this: the property notebook or the VRSet function. 
When you use a file, its name must be surrounded with parentheses. Most of the 
HelpText properties in Music-5 were set using the SetHelp subroutine that’s called 
by the Init subroutine. The beginning of that subroutine is as follows: 


SetHelp: 

Okay = VRSet("Windowl", "HelpText", "(PIANO.TXT)") 

Okay = VRSet("DT_Titie", "HelpText", "(PIANO.TXT)") 

Okay = VRSet("PB_C1", "HelpText", "(PIANO.TXT)") 

Okay = VRSet("PB_C1S", "HelpText", "(PIANO.TXT)") 

(The subroutine continues to assign PIANO.TXT to all the keys.) Naturally, PIANO.TXT 
must be in the same subdirectory as Music-5 or you must specify the full path to the file. 

Note that ERROR.TXT isn’t assigned to the objects in the error window in this 
code. Since that window hasn’t yet been opened, the assignment would fail at this 
point. The code to assign ERROR.TXT as the help file for objects in the error window 
is added to the subroutine that opens the error window. Figure 16.6 shows Music-5 
running and displaying its help file for the error window. 

There’s one important limitation to using ASCII files you must be aware of when 
distributing your programs to other users. Since the help text exists as an ASCII file, 
anyone with an editor can modify it. This is particularly important if you’re writing a 
shareware program and your help file provides a name and address to send money to. 


Hints 


In addition to help, VX-REXX supports a type of help called hints. Hints are brief 
single-line messages that pop up in the main window when an object is highlighted, 
much like balloon help under System 7 on the Macintosh (only not as obnoxious). 

Each object has its own hint assigned to it. As with the HelpText property, you can 
assign the HintText property by using either the property notebook for that object or 
the VRSet function. By default, a program doesn’t display hints. In order to show 
hints, you must enable hints using the property notebook of the main window and you 
must tell the window where to show the hints. You can use either the top or bottom of 
the screen. Figure 16.7 shows the top of the Viewlcn3 screen with the hint showing. 


Summary 

This chapter shows how to add help to a file using an IPF-compiled help file, assign¬ 
ing the text to the HelpText property and an ASCII file to the HelpText property. It 
also shows how to add brief help messages, called hints, to programs. 
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Error 


A music file is a special ASCII file that contains 
the notes for the program to play. This music file 
contains an error. 

The first line of the music file must be the 
name of the song with nothing else on that tine. 
The remainder of the file are the notes, with a 
space, comma or Return between notes. Only one 
divider between notes is allowed. Also, the notes 
must be entered in uppercase. 

Entering an open parenthesis "(" in the notes 
increases the length of time it is held. Multiple 
parentheses may be used and they may be placed 
anywhere in the note. Adding an "S'' to the end of 
the note, without the quotation marks, makes that 
note a “sharp" note. The "I" note causes the song 
to pause for the length of one note. Tunes may be 
as long as you Like. 


■:o| 


Figure 16.6 Music-5 showing its error window help screen. 
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Figure 16.7 Hints are displayed at the top of the program just under the window, or at the bottom of the 
program. This figure shows the top of the Viewlcn3 program, showing a hint. 


Todo-4 is a modified version of Todo-3 with help added via an IPF-compiled help 
file. Viewlcn3 is a modified version of Viewlcn2 in which text was assigned to the 
HelpText property to create help. Music-5 is a modified version of Music-4 where 
ASCII files were assigned to the HelpText property to create help. 

Following is the ASCII listing for the file TODO-5.IFP: 


TODO-5.IPF 
ruserdoc. 

:title.Todo Help Facility 


: doeprof. 


* 

* 


General Information 


:hi res=1500. Extended Help 


Todo is a demonstration program for maintaining a todo list. It is included 
with the OS/2 VX-REXX Programming book by Ronny Richardson. 
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: p • 

Todo stores a priority (l=high 2=medium 3=low) code and an brief description 
of the todo item. The data is stored in a simple ASCII file of the format: 

:p. 

:lines. 

Priority #1 
Description #1 
Priority #2 
Description #2 
Priority #3 
Description #3 
and so on 
:elines. 

:p. 

Todo items are sorted into priority order before they are saved. Within each 
priority, items are sorted into alphabetical order. 

:p. 


:hi res = 1501. Priority 

:p. 

The priority is used to group todo items into low, medium and high priority 
groups. The program automatically lists all of the high priority items first, 

followed by the medium priority items and then the low priority items. 

Normally, you would work on high priority items first, then medium priority 
items and finally low priority items. Priorities can be changed at any time 
by just clicking on a different RadioButton. Items are not resorted when a 

priority is changed or a new item is entered until the data is saved. 


C 


Priority 


res=1501. Priority 


. * Todo Items 

:hl res=1502. Todo Items 
: P • 

The todo items are the things you want to accomplish. They should be as brief 
as possible but long enough to be descriptive. Within priorities, todo items 
are sorted in alphabetical order so it is a good idea to make the first few 
words of the todo item to be as descriptive as possible. Todo items can be 
changed at any time by just clicking on the EntryField and editing the text. 
Items are not resorted when they are changed or a new item is entered until 
the data is saved. 


:p. 

* 

* 

:hi res=1503. Saving Data 

Changes, additions and deletions made while running the Todo program are not 
permanent until those changes are written out to the hard disk. The save 
option on the menu does this. Additionally, the data is sorted prior to being 
saved. This is the only way to sort the data. 

: P • 



:hi res = 1504. Scrolling 

The Todo program can only display twelve todo items at a time. When the todo 
list contains more than twelve items, you must scroll through the data file 
to see all the items. Forwards moves you towards the lower priority items in 
the file while backwards move you towards the higher priority items in the 
f ile. 



• y • . 

Where scrolling forwards, the program is configured so the last item on the 

current screen will be the first item on the next screen. This provides a 
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visual clue of movement. When less than twelve items remain for scrolling, 
the program is configured to display the last item in the file is in the last 
spot on the screen, even if the last item on the current screen does not 
become the first item on the next screen. 

:p. 

Where scrolling backwards, the program is configured so the first item on the 
current screen will be the last item on the next screen. This provides a 
visual clue of movement. When less than twelve items remain for scrolling, 
the program is configured to display the first item in the file is in the 
first spot on the screen, even if the first item on the current screen does 
not become the last item on the next screen. 


:p. 


Adding Items 


:hi res=1505. Adding 

:p. 

This is used to add new items to the todo list. A dialog box appears and asks 
you to enter the new todo item. Once you have finished, you click on the low, 
medium or high priority button to indicate the item's priority. Clicking on 
cancel causes the new item to be discarded. 

;p. 



:hi res = 1506. Erasing 

:p. 

Erasing an item removes it from the todo list without saving a copy in the 
"Dune" file. You use this to remove todo items you no longer plan to 
complete. You are asked to confirm your action. 



:hi res=1507. Done 
: P • 

This tells the program you have completed a todo item. Its contents are 
removed from the todo file and placed in a special file containing only 
completed items. The time and date when you marked the item as done are also 
added to the file. You are asked to confirm your action. 



:hi res=1508. Printing 

:p. 

This sends a copy of the current todo list to the printer. The list is not 
sorted first so if you have made changes to the todo list you should save it 
first. 


:p. 


About 


:hi res = 1509 . About 


:p. 

This provides a brief explanation of the program. 
: P • 


Quit 


: hi res = 1510. Scrolling 


: P • 

This exits the program. If the data has been modified since the last time 
saved it, you will be asked to confirm your action. 


you 
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:P- 

:euserdoc. 

PIANO.TXT 

Piano 


Piano is a simulated piano keyboard that runs under the OS/2 Presentation Manager. 
It presents two octaves of notes on the screen. The user can click on the notes to play 
a tune or the user can write a “music file” and use the program like a player piano. 

A music file is a special ASCII file that contains the notes for the program to play. 
The first line of the music file must be the name of the song with nothing else on that 
line. 

The remainder of the file are the notes, with a space, comma or Return between 
notes. Only one divider between notes is allowed. Also, the notes must be entered in 
uppercase. 

Entering an open parenthesis “(” in the notes increases the length of time it is 
held. Multiple parentheses may be used and they may be placed anywhere in the 
note. Adding an “S” to the end of the note, without the quotation marks, makes that 
note a “sharp” note. The “! ” note causes the song to pause for the length of one note. 
Tunes may be as long as you like. 

Piano processes the music file when you load it and invalid notes are ignored in 
the song. However, the program does display an error screen during this processing 
which lists every error it encounters. Should there be too many errors to display 
them all, this error window does not support scrolling. 




Chapter 

17 

Multithreaded Applications 


Both Windows and OS/2 are multitasking environments; that is, they allow more than 
one application to run at once. They both do this in a similar fashion. They rapidly 
switch between each active application hundreds of times per second, allowing each 
application to run briefly before control is turned over to the next application. Under 
OS/2 this switching is cooperative, while under Windows it’s preemptive. 

At the program level, however, most Windows programs allow you to do only one 
thing at a time while in that program. For example, if you’re in a database perform¬ 
ing a long sort or index, you can’t use that same database at the same time to write 
a report. A single exception to this is that some Windows word processors allow you 
to work while printing. They typically do this by spooling output to the Print Man¬ 
ager and then multitasking between the word processor and Print Manager, or by 
starting another program to handle printing. 

Native OS/2 programs can be multithreaded. A thread is a particular sequence 
of commands or instructions within a program, so multithreaded means nothing 
more than running more than one thread at the same time in a single program. As 
a result, a database under OS/2 can run one thread with the instructions required 
to sort or index, while simultaneously running another thread with the instruc¬ 
tions required to generate a report. While OS/2 allows programs to be multi¬ 
threaded, it doesn’t require it nor does it automatically add multithreaded 
abilities to a program. Support for multiple threads must be designed into the pro¬ 
gram from the beginning. This chapter will show you how to design your VX- 
REXX programs to be multithreaded. 

When Should a Program Be Multithreaded? 

Since a user can pay attention to only one thing at a time, it makes little sense to 
have a program run two threads that both require the user’s attention. Thus, it 
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wouldn’t be sensible to run a word processor with both spell-checking and search- 
and-replace functions in different threads. Since the user’s attention is required for 
both, only one at a time could get the attention it required. 

Nevertheless, it might make sense to give these two processes their own threads. 
That way, users could start a long thread to do something that didn’t require their at¬ 
tention—such as printing or mail merge—and then turn to the second thread to ei¬ 
ther check the spelling or do a search and replace. 

As a general rule, your program needs to meet the following criteria before it 
makes sense to spend the extra time and effort to make it multithreaded: 

■ At least one of the processes will take a long time. After all, it makes little sense to 
generate a thread to handle something that’s over very quickly. Keep in mind that 
speed is relative. What seems fast on a 486/66 can take forever on a 386/20. 

■ At least one of the long processes will run with little or no user interaction. This 
could be a long series of actions that truly don’t need user interaction, such as 
printing or sorting, or a process that requires some user interaction at the start of 
the thread but can run unattended after that. 

■ There’s something the user can be doing while the unattended thread is running or 
there’s the option of more than one unattended thread running at once. If the user 
has nothing to do while the thread is running, then the program might as well be 
single-threaded. 

When your program meets these criteria, making it multithreaded can make it seem 
much faster and greatly improve user satisfaction. 

A multithreaded application seems faster because users don’t have to wait on the 
computer to perform some long task, which makes them perceive the program as 
slow. However, a multithreaded application won’t generally run faster. Your com¬ 
puter has only one processor and a certain amount of memory and storage space— 
and all the threads must share these. 


More on Threads 

Every program you write has at least one thread, called the main thread. This is the 
thread OS/2 automatically starts to run the program. A program that uses just this 
main thread and doesn’t start any other threads is said to be single-threaded. 

The VX-REXX manual uses an analogy for multithreaded applications that I like a 
lot, so I’m going to expand on it a little here. Think of your main program as a com¬ 
pany. This company goes about its normal business. However, when something out 
of the usual crops up, the company hires several consultants to take care of that 
problem. For example, they’re sued by an employee so they hire a team of attorneys 
to handle the defense. These consultants work for the company and are under the 
control of the company, but they work independently. The company can terminate 
the consultants at any time, get information from them, or hire more consultants as 
they see fit, but otherwise the company continues with its normal business. In this 
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example, the company is the main thread and its consultants are the additional 
threads it starts. 


Designing a Multithreaded Application 

A good way to design a multithreaded program is to first write it as a single- 
threaded application. Get the program debugged and running before you worry 
about introducing the additional complexity of multiple threads. As an additional 
advantage, you can experiment with your single-threaded application to see 
which actions take enough time that it makes sense assigning them to an inde¬ 
pendent thread. 

One way to arrange the threads in your program is by using the manager/worker 
model. In this model, the main thread functions as the manager thread and starts all 
additional threads. Thus, even if there are dozens of threads, all of them are gener¬ 
ated by the manager thread. This makes tracking and controlling the threads fairly 
easy, and most VX-REXX programs will easily fit this model. 

Any thread can create an additional thread that reports to it. This leads to a 
second way to arrange the threads in your program—the company model. A large 
company might have a president who has several vice presidents reporting to him 
or her. All the vice presidents might have several managers reporting to them, 
with the managers having several workers reporting to them. While there’s still 
one overall controlling entity—the president—the workers are now so scattered 
throughout the organization that the president would have a difficult time con¬ 
trolling them all. Just as the president of this company would find it difficult or 
impossible to control all the workers, your program would find it difficult or im¬ 
possible to control all its threads. For that reason, it’s best to avoid this model 
when writing multithreaded programs. 


Writing a VX-REXX Multithreaded Program 

There are four things your program can do with a thread: 

■ Start the thread. 

■ Communicate with the thread. 

a Get information about the thread. 

■ Stop the thread. 


Starting a thread 

Threads are normally stored in a separate file within your overall program. The com¬ 
mand to start a thread is: 


threadID = VRMethod("Application" , "StartThread ", "file", arguments) 
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where: 

■ ThreadID is the ID number assigned to this thread. VX-REXX assigns this auto¬ 
matically. This number is needed to communicate with the thread, to get informa¬ 
tion about it, and to stop it. 

■ Application is the Application object. Each program has exactly one Application 
object and VX-REXX creates it automatically. Its purpose is for referring to appli¬ 
cation-wide entities. 

■ StartThread is the method used to start a new thread. 

■ File is the name of the file containing the code for the thread. If no extension is 
used, VX-REXX assumes that the file is part of the project. If not, it adds a .CMD 
extension and searches your path for the file. 

■ Argument is any arguments that need to be passed to the thread. These should be 
separated by commas, just like any other REXX arguments. Since the thread 
doesn’t have access to variables or objects from the main program, any information 
it needs to run or access objects on the screen must be passed to it. 

Instead of using a file to start a thread, you can pass REXX code directly to the 
thread. Only very simple code can be passed in this fashion. To illustrate this, I put 
together In-Line, a demonstration program that uses in-line code to create a thread 
to beep the speaker 20 times. The Click event that creates the thread using in-line 
code is: 


RunThr e ad_Click: 
Code = '/**/' 
Code = Code 
Code = Code 
Code = Code 
Code = Code 


! 'OdOa 1 x 

' DO I = 1 TO 2 0 1 !! 

'CALL Beep 100, 100' 
'END' !! 'OdOa'x 
'EXIT' !! 'OdOa'x 


OdOa'x 
! ! 'OdOa'x 


Okay = VRMethod("Application", 
return 


"StartThread", Code) 


In-line code must begin with a /**/ so OS/2 recognizes it as REXX code. Most of the 
time the code is complex enough, however, that a separate file is used rather than in¬ 
line code. 

VX-REXX limits you to 200 threads. OS/2 also limits the total number of threads 
that can be running across all processes. This is set in the CONFIG.SYS file and is 
generally high enough that VX-REXX programmers don’t have to worry about it. 


Communicating with a Thread 

When you need to pass information to a thread and the information is known when the 
thread is started, the easiest way to pass the information is as a series of arguments on 
the line that starts the thread. When the data is not known when the thread starts, you 
can use the PutVar and GetVar methods to pass information back and forth. 

When a worker thread needs to communicate with the manager thread that cre¬ 
ated it, it must use the PostQueue method to tell the manager thread to run a par- 
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ticular subroutine and, perhaps, pass some results back. The syntax for the com¬ 
mand in the worker thread is: 


Okay = VRMethod("Application", "PostQueue", threadID, queuelD, event, 

[info, value] [...]) 


where: 

■ Application is the Application object. 

■ PostQueue is the method used to insert an event string into the event queue of an¬ 
other thread. 

a ThreadID is the ID of the thread that’s to have the event posted to its queue. When 
this is the primary thread, the value is 0 or a null string. 

a QueuelD is the identifier of the event queue to insert this event into. A value of 1 
posts the event to the thread’s primary event queue. 

■ Event is the string that’s inserted into the event queue. Typically, this would be 
CALL subroutine , where subroutine is the name of a subroutine to execute. 

■ Info and value are pairs of strings used to return values. Info is the name of the in¬ 
formation to be used by the VRInfo function and value is the value returned by the 
VRInfo function. You can use multiple pairs if more than one value needs to be re¬ 
turned. 

You can see this in action with the Post Back program. Post Back is a demonstration 
program in which a thread computes a number and then the PostQueue method 
transfers this information back to the main thread, where it’s displayed in a Descrip¬ 
tive Text object. 

The Click event that starts the new thread first displays a message in a Descriptive 
Text object and then disables the two PushButton objects. After that, it starts the 
thread and passes it the number of loops to execute. Be careful not to set this value 
too high because the loop value controls three loops, so a small change in the value can 
cause a large change in the length of time the loop runs. For example, doubling the 
value will cause the thread to run eight times longer! The code for this Click event is: 

RunThread_Click: 

Okay = VRSet ("DT__1" , "Caption", "Thread Running") 

Okay = VRSet("RunThread", "Enabled", 0) 

Okay = VRSet("Quit", "Enabled", 0) 

ThreadID = VRMethod("Application", "StartThread", "Thread", 20) 

return 


The thread first goes through three loops to create an answer to return to the main 
thread. After that, it calls the main thread and tells it to execute the ThreadDone 
subroutine. It also passes the Answer back along with the info name of TheAnswer. 
That code is as follows: 


Main: 

Answer = 1 
Limit = Arg(l) 
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DO I = 1 TO Limit 

DO J = 1 TO Limit 
DO K = 1 TO Limit 

Answer = Answer + Random(1,10) 

END 

END 

END 

Okay = VRMethod("Application"PostQueue",0,1,"CALL ThreadDone", 
"TheAnswer",Answer) 

exit 


The ThreadDone subroutine first beeps the speaker, then displays the answer in a 
Descriptive Text object, and finally enables the PushButton objects. The code is: 


ThreadDone: 

DO 1=1 TO 5 

CALL Beep 500, 500 

END 

Answer = VRInfo("TheAnswer") 

Caption = "Thread Is Done, Answer Is:" Answer 
Okay = VRSet("DT_1", "Caption", Caption) 

Okay = VRSet("RunThread", "Enabled", 1) 

Okay = VRSet("Quit", "Enabled", 1) 
return 


Getting information on threads 

A program can get a list of all the currently running threads with the ListThreads 
method. Each thread can get its own thread ID with the GetThreadID method. 


Stopping a thread 

Any thread except the main thread can be stopped with the HaltThread method. The 
syntax is: 

Okay = VRMethod("Application", "HaltThread", threadID) 

where Application is the Application object, HaltThread is the method used to stop 
the thread, and threadID is the number of the thread to stop. 

Working 

Working is a demonstration program that displays a blinking message while it per¬ 
forms a long series of calculations. VX-REXX can’t create a blinking message. Origi¬ 
nally, I tried to use a Timer object to change colors at regular intervals. By alternating 
the foreground color between a unique color and the background color, the caption 
would appear to blink. However, Timer events are queued while the program per¬ 
forms calculations, so the colors don’t change while the calculations are being per¬ 
formed. Additionally, only one Timer event is queued. The solution was to place the 
message and its associated Timer object on a separate thread so the Timer object 
would operate normally while the main thread performed the calculations. 
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The user interface for Working consists of just two PushButton objects—one to 
start the demonstration and another to exit the program. The Click event for the 
button to start the demonstration first calls the Working subroutine with an ON flag, 
works through a long series of calculations, and then calls Working with an OFF flag. 
The code is as follows: 


PB_Demo_Click: 

CALL Working ON 

DO I = 1 TO 10000 

Total01 - Random() 
Total02 = Random() 
Total03 = Random() 
Total04 = Random() 
Total05 = Random() 
Total06 = Random() 
Total07 = RandomO 
Total08 = Random() 
Total09 = Random() 
Total10 = Random() 

END 

CALL Working OFF 
return 


* Random() 

* Random() 

* Random() 

* Random() 

* Random() 

* Random() 

* Random() 

* Random() 

* Random() 

* Random() 


When the Working subroutine is passed an ON flag, it starts the thread that displays 
the “Working” message and disables the two PushButton objects. When it’s passed 
an OFF flag, it stops the thread it created earlier and enables the two PushButton 
objects. The Working subroutine is: 


Working: 

Flag = Arg(l) 

IF Flag = "ON" THEN 
DO 

Thread = VRMethod("Application", "StartThread", "Windowl") 

Okay = VRSet("PB_Demo", "Enabled", 0) 

Okay = VRSet("PB_Quit", "Enabled", 0) 

END 

ELSE 

DO 

Okay = VRMethod("Application", "HaltThread", Thread) 

Okay = VRDestroy("Windowl") 

Okay = VRSet("PB_Demo", "Enabled", 1) 

Okay = VRSet("PB_Quit", "Enabled", 1) 

END 

return 


The Timer object Trigger event in the thread file simply alternates the color of the 
“Working” message between red (the background color) and white. This causes the 
message to appear to blink. Since the window is created by the thread, the object 
names can be the same as in the main routine and no special steps are required to 
address these objects. The code for this subroutine is as follows: 


Timer_Trigger: 

IF Color = "RED" THEN 
DO 


Color 


"WHITE" 
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Okay = VRSet( "DT_1", "ForeColor", "White" ) 

END 

ELSE 

DO 

Color m "RED" 

Okay = VRSet( "DT_1", "ForeColor", Red ) 

END 

return 


Figure 17.1 shows Working while it’s running and displaying its message. For an addi¬ 
tional look at multithreaded applications, please see the Queue program at the end of 
Chapter 18. Queue is a multithreaded demonstration program that immediately starts 
four threads to read data from four external data queues. The results of these four 
threads are shown on the right side of the screen in separate Descriptive Text objects. 

Four additional threads are under user control. Each of these threads sends data 
to one of the external data queues being read by the original threads. The lines they 
place in their respective queues are shown in their Descriptive Text object on the left 
side of the screen. Each time one of these threads is invoked, 100 lines of data is 
placed into the queue. Since each Descriptive Text object is serviced by its own 
thread, all eight can be updated at once. 


Summary 

This chapter shows how to write multithreaded applications, and explains when a 
multithreaded approach is appropriate and when a single-threaded approach is best. 
The In-Line program demonstrates how to start a thread and pass it in-line code. The 
Post Back program shows how a thread can send information to another thread. The 
Working program uses a thread to cause a message to blink on the screen. The Queue 
program in Chapter 18 uses eight threads to send and receive information across four 
different REXX external data queues. 



Figure 17.1 The Working program running. It uses a thread to display 
a blinking message while the main thread is performing complex cal¬ 
culations. 


Chapter 



Using the External Data Queue 


How would you like for one of your REXX or VX-REXX programs to be able to com¬ 
municate with another REXX or VX-REXX program, even if that second program is 
running in a different session? Or even if that second program runs much later than 
the first program? If you answered yes to either of these questions, then the REXX 
external data queue is the answer you’re looking for. 

REXX external data queues can be hard to understand and are rarely used in 
REXX programming, so you might not be familiar with them. For that reason, I’ll re¬ 
view external data queues in REXX first without referring to VX-REXX. Then I’ll 
show you how to use the external data queue in VX-REXX programs. 

The normal form of communications between a REXX program and user is a 
stream of characters that can be acted on either on a per-character or per-line basis. 
The normal form of communications between a REXX program and its external sub¬ 
routine is a series of arguments going from the main program to the external sub¬ 
routine and a single number or character string returning from the external 
subroutine to the calling program. The arguments are acted on in a per-argument 
fashion while the returning number of character string must be acted on all together. 
The external data queue is a line-based form of communication that differs from ei¬ 
ther of these other methods. 

Before REXX, OS/2 had several means of interprocess communications that C 
(and other languages) could use. One of these used a data structure that OS/2 called 
a queue. Meanwhile, before OS/2, REXX was on other systems, and it included a data 
structure called a queue. As it happens, the OS/2 queue behaved differently than a 
REXX queue, so they’re two different things. If data is in an OS/2 queue, a REXX pro¬ 
gram can’t touch it with any of the REXX queueing instructions, and vice versa. 

There are application program interfaces (API) that allow C programs to read and 
write to REXX queues, but IBM hasn’t documented them. The Personal REXX pro¬ 
grams from Quercus Systems support the same APIs, and documentation on how other 
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programs can interface with REXX queues is available from Quercus Systems. This 
chapter contains three demonstrations to illustrate the power of external data queues. 

GETDATA.CMD and SENDATA.CMD 

First, open two OS/2 command-line sessions. Now, in one of the sessions (it doesn’t 
matter which) run GETDATA.CMD. Nothing will appear to happen. GETDATA.CMD 
is waiting for data to be placed in an external data queue. Now switch to the second 
window and run SENDATA.CMD. You’ll see it run and display its progress on the 
screen. It places 101 lines of data into an external data queue. Now switch back to 
the session running GETDATA.CMD and you’ll see that it has read in and displayed 
100 lines of data. The last line was a TERMINATE, which the program uses as a flag 
to indicate that no more data is coming. This was programed into the logic; it isn’t 
part of a REXX command. 

GETDATA.CMD then SENDATA.CMD 

Now, with only one command-line session open, run SENDATA.CMD. After it fin¬ 
ishes, close the session. Now reopen that session or open a new session. Once you 
have a session open, run GETDATA.CMD. You’ll see that, even though the command¬ 
line session was closed, OS/2 maintained the data in the external data queue until 
another program was run to read it out of the queue. As long as you don’t reboot or 
turn the computer off, it doesn’t matter how long you wait between sessions. 

SENDATA2.CMD 

You might recall that REXX external subroutines can return only one number or one 
character string to the calling program. That isn’t the case when the transfer is com¬ 
pleted with an external data queue. SENDATA2.CMD calls an external subroutine that 
places 101 lines of data into an external data queue called RONNY2. Again, this is 100 
lines of data plus a line saying TERMINATE to tell the program that no more data is 
coming. You can see this by running SENDATA2.CMD in a command-line session. 
When a calling program needs to send a lot of data to an external subroutine, it too 
might rely on the external data queue rather than trying to send them all as arguments. 

In order to make sure the external subroutine is available, SENDATA2.CMD calls it¬ 
self as an external subroutine. Logic at the top of the program handles the branching, 
so SENDATA2.CMD can run both as a calling program and as an external subroutine. 

Understanding External Data Queues 

REXX actually works with three different types of queues: session queues, detached 
session queues, and external data queues. Since each of these works with data, a 
common generic term is data queue . 

Session queue. This queue is created automatically for REXX by OS/2 when the 
REXX program first transfers data, say between the keyboard and the program. It 
has the name of SESSION and is managed by OS/2. 
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Detached session queue. A detached session queue is a special version of a session 
queue. OS/2 allows you to run a program, batch file, or internal command “detached” 
from its command processor by preceding its name with the OS/2 (not REXX) DE¬ 
TACH command. OS/2 automatically generates a unique name for this queue. OS/2 
also manages this queue. 

External data queue. An external data queue is a stream of characters stored by 
OS/2 external to any active REXX program. Since it’s external to REXX, other pro¬ 
grams can place characters into and read characters from the stream. None of the 
characters in the external data queue have any special meaning to OS/2, other than 
the Return character marking the end of a line. REXX can read data from the exter¬ 
nal data queue only by using line-orientated instructions. Additionally, the external 
data queue is managed by REXX rather than by OS/2. Outside of REXX, the external 
data queue must be managed by whatever program is accessing it. 

Think of each external data queue as a length of pipe containing data. REXX pro¬ 
grams have the ability to create new pipes, add data to existing pipes, and remove 
data from an existing pipe. As you’ll see later, data can be added to either end of the 
pipe. When a REXX program accesses a pipe and reads data, that data is removed 
from the pipe. 

Managing the External Data Queue 

Management of an external data queue is up to the REXX program rather than OS/2. 
This section discusses the REXX tools for managing a queue. 

Creating a new queue 

The first thing you must do in managing any queue is create it. In order to create a 
queue, that queue must have a name. You have two options for generating a name— 
supply one yourself or let OS/2 pick a unique name. The RxQueue internal function 
is used in either case. The syntax for creating an external data queue with OS/2 sup¬ 
plying the name is: 


QueueName = RxQueue("Create") 


The function returns the queue name to be stored in the QueueName variable. Of 
course, you can use any legal variable name. To supply the name, the syntax is: 


QueueName = RxQueue("Create", Name) 


where Name is either a variable containing the queue name or a character string. If 
the queue named in the Name variable exists, OS/2 will create the queue but give it 
a unique system name just as though you hadn’t supplied a queue name. That name 
is returned to the QueueName variable. For that reason, it’s usually better to run Rx¬ 
Queue as a function returning a queue name and then use that returned name rather 
than using the CALL instruction, unless you’re very sure the queue doesn’t already 
exist. Additionally, only the first letter of the subinstructions, like Create, needs to 
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be supplied and capitalized, and queue names are immaterial. The Create subin¬ 
struction can be seen in the QUEUE-1.CMD program that comes with this book. 

Making a queue active 

Once you’ve created a queue, the next step is to make it the active queue. The syn¬ 
tax to do that is: 


OldQueue = RxQueue("Set", name ) 


where name is the name of the queue to make active. The name of the previously 
active queue is returned so it can be saved as OldQueue to be made active again 
later if that’s required. This can be seen in the QUEUE-1.CMD program that 
comes with this book. 

Putting data into a queue 

Once a queue is active, data can be written to it. Recall that an external data queue 
is line-orientated, so data can be added only one line at a time. REXX offers two in¬ 
structions, PUSH and QUEUE, specifically for writing data to the currently active 
queue. Their syntax is: 

PUSH expression 
QUEUE expression 

where expression is the line to be added to the queue. The PUSH instruction places the 
line at the head of the queue, in last-in-first-out or LIFO order. The QUEUE instruction 
places the line at the tail of the queue, in first-in-first-out or FIFO order. Both of these 
instructions can be seen in the QUEUE-1.CMD program that comes with this book. 

Since the queue is a line-orientated data source, data can also be added with the 
internal LineOut function, using QUEUE: as the name of the output stream to write 
to. This can be seen in the SENDATA.CMD program that comes with this book. 

Putting data into a queue from the command line 

OS/2 offers the RXQUEUE.EXE filter to allow data to be added to the queue from the 
OS/2 command line. (To avoid confusing the RXQUEUE.EXE filter with the Rx¬ 
Queue internal function, I’ll always refer to the filter as RXQUEUE.EXE.) RX¬ 
QUEUE.EXE also proves that other programs can successfully write to a REXX 
queue. The syntax for using RXQUEUE.EXE is: 

RXQUEUE.EXE [ queuename] [/flag] 

where queuename is the name of the queue to add the data to. If none is specified, 
the default queue is used. Flag is one of the three following optional flags: 


FIFOo This causes the data to be appended to the tail of the queue. 
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LIFO. This causes the data to be appended to the head of the queue. 

CLEAR. This causes the queue to be cleared of all data. 

Remember, these are OS/2 commands and not REXX commands. Of course, a 
REXX program can issue this command to the operating system, just like any other 
command. This can be seen in the QUEUE-2.CMD program that comes with this book. 

Getting data from a queue 

Data is removed from the queue using the standard PARSE and PULL instructions. 
This can be seen in action in the QUEUE-2.CMD program that comes with this book. 
Data can also be removed with the Lineln internal function, using QUEUE: as the 
name of the output stream to read from. This can be seen in action in the GET- 
DATA. CMD program that comes with this book. While you have the option of writing 
to the head or tail of the queue, data is always read from the head of the queue. 

The PARSE and PULL (converts to uppercase) instructions are different from the 
Lineln internal function. The PARSE and PULL instructions will automatically 
switch over and read data from the keyboard (the standard input stream) when data 
in the external data queue is exhausted, while the Lineln function won’t. 

You can see this by running the QUEUE-4.CMD program that comes with this 
book. QUEUE-4.CMD places a first name and last name (Ronny and Richardson , 
respectively) into the external data queue and then calls QUEUE-3.CMD. QUEUE- 

3. CMD reads a first name, last name, and age using the PARSE PULL instruction. 
Since two lines have been placed into the queue, QUEUE-3.CMD reads the first and 
last name from the queue and then prompts the user for an age. (Even though the 
first and last name come from the queue, the request for information prompt still 
shows because it’s just a SAY instruction.) Once an age is entered, QUEUE-3.CMD 
displays the results and then terminates. 

After QUEUE-3.CMD terminates and returns control to QUEUE-4.CMD, QUEUE - 

4. CMD again places a first and last name into the external data queue and then calls 
QUEUE-5.CMD as an external subroutine. QUEUE-5.CMD tries to read the first 
name, last name, and age using the Lineln internal function. Since only two lines are 
in the external data queue, the program will wait forever on the third call to the 
Lineln function. While the prompt is showing (it’s just a SAY command), the Lineln 
function won’t accept input from the keyboard. You must press Ctrl-Break to abort 
QUEUE-5.CMD. 

You can use this to your advantage. If you write your REXX programs to get all 
their input using the PARSE or PULL instructions, then you can always call the pro¬ 
grams from another REXX program and supply them with all the inputs they want by 
having the calling program place those inputs into the queue. You can even use the 
RXQUEUE.EXE filter to pipe responses in from the command line and then have the 
program run unattended. 

If you don’t know the number of lines to expect, the internal Queued function will 
return the number of lines pending in the currently active queue. The program can 
read from the queue in a loop until the Queued function returns a zero, as QUEUE- 
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2.CMD does; the sending program can send a special line to mark the end of data, as 
SENDATA.CMD does; and the program reading from the queue can test for that spe¬ 
cial line, as GETDATA.CMD does. This second method works well when an external 
subroutine is using an external data queue to return data to the calling program. 

Finding the active queue 

If you need to find the name of the current queue, the syntax is: 


ActiveQueue = RxQueue("Get") 


where ActiveQueue is the variable to store the name of the currently active queue. 

Deleting a queue 

Once you’ve finished with a queue, you can delete it. The syntax is: 


code=RxQueue("Delete", name) 


where name is the name of the queue to delete and Code is the variable to contain 
the return code. Possible values are: 

0. The queue was successfully deleted. 

5. An invalid queue name was supplied to the function. 

9. The queue to be deleted doesn’t exist. 

10. The queue to be deleted is busy. 

12. A memory error has occurred. 

1000. An initialization error has occurred. 

It isn’t an error to delete the current queue. However, this causes the program to 
not have an active queue, which will result in an error if any queue activity takes 
place. To avoid this, always make another queue active after deleting the active 
queue or replace an active queue with another queue before deleting it. 

Avoiding Conflicts 

An external data queue is never private. That is, other applications can also write 
data to the queue. This can be a particular problem when you write data to an exist¬ 
ing queue and expect to read that data back from the queue. This works as you ex¬ 
pect only when the queue is empty. When the queue contains data, you run the risk 
of reading in that data rather than the data your program expects. 
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You can, of course, avoid this by always creating your own queues. Another way to 
avoid the problem is to always place data at the head of the queue using the PUSH 
instruction. That way, if 50 lines of new data are added to the head of the queue and 
your program then reads 50 lines, it will get its own data no matter if the queue con¬ 
tains existing data or not. Of course, if the order of the data is important, you must 
go through the extra step of writing it to the queue in reverse order. 

Using External Data Queues in VX-REXX 

All VX-REXX does is manage objects on the screen; the remainder of your programs 
are REXX code. Therefore, external data queues can be used in VX-REXX just as 
they can in REXX. The extra abilities of VX-REXX, however, allow you to communi¬ 
cate with external subroutines. External data queues are less useful in VX-REXX 
than they are in REXX, but there are circumstances where they can be very useful. 
We’ll look at three VX-REXX programs that use the external data queue. 


Send Data 

Send Data is a demonstration program that sends 100 lines of data out using the 
Ronnyl REXX external data queue. These 100 lines of data are followed by a TER¬ 
MINATE line. This has no special meaning to REXX or OS/2, but the program that 
reads in the data from the external data queue uses this line as a flag to figure out 
when it has received all the data from the queue. The program is stored in the \Q2Q 
subdirectory. 

Strictly speaking, a special flag isn’t required to signal to a REXX program that the 
end of the data has been reached since REXX has its own ways of figuring out when 
the queue has been exhausted. However, it’s good practice to include a flag when it’s 
possible that more than one program is writing to the queue. 

Send Data has a fairly simple user interface. A Descriptive Text object displays 
the data that’s written to the external data queue. One PushButton object starts 
sending the data and another terminates the program. Send Data allows the user 
to send only one packet of data. After that, the PushButton object, which initiates 
sending the data, is disabled. The Click event for this object is as follows, with 
numbers added: 


1. 

Send_Click: 



2 . 

Line. = "" 



3 . 

Okay = RxQueue("Create", "Ronny") 


4. 

Okay = RxQueue("Set", "Ronny") 



5 . 

DO I = 1 TO 100 



6. 

DO J = 1 TO 6 



7 . 

+ 

ii 



8 . 

Line.J = Line.K 



9. 

END 



10 . 

Info = "Line Number " ill": 

Random Number" RANDOM(1,100) 

11. 

Line.7 = Info 



12 . 

Caption = Line.l !! "0d"x !! 

Line.2 ! ! 

"0d"x !! Line.3 

13 . 

Caption = Caption !! "0d"x ! 

! Line.4 ! 

! "0d"x 1i Line.5 

14 . 

Caption = Caption !! "0d"x ! 

! Line.6 ! 

! "0d"x ! ! Line.7 

15 . 

CALL LineOut "QUEUE:", Info 
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16. Okay = VRSet("Text", "Caption", Caption) 

17. END 

18. CALL LineOut "QUEUE:", "TERMINATE" 

19. Okay = VRSet("Send", "Enabled", 0) 

20. return 


Line 2 resets a stem variable that’s used to store the lines of data displayed in the De¬ 
scriptive Text object. Line 3 creates the queue and line 4 activates it. Line 5 loops 
100 times to send the data. Lines 6-9 move the lines of data in the Descriptive Text 
object up by one to scroll the display and make room for another line. Line 10 cre¬ 
ates a line of data using a random number generator. Line 11 stores this to the stem 
variable, and lines 12-14 create a variable containing the caption for the Descriptive 
Text object. Line 15 places the line of data into the queue, line 16 displays the text 
in the Descriptive Text object, and line 17 terminates the loop. Line 18 sends the ter¬ 
minated line of data to the queue. Line 19 turns off the PushButton object that 
started sending data through the queue. 

Figure 18.1 shows Send Data running and placing data into the external data 
queue. Once this data is in place, it can be read by the Getdata program. 


Get Data 

Get Data is a demonstration program that reads the data from the external data 
queue that was placed there by Send Data. The program is stored in the \Q2Q sub¬ 
directory. 

Get Data is practically the reverse of Send Data. Its Click event reads in lines from 
the Ronnyl external data queue until it receives a TERMINATE line. Each line is dis¬ 
played in a Descriptive Text object just like Send Data. The screen consists of a sin¬ 
gle Descriptive Text object for displaying the data, a PushButton object to receive 
the data, and another to quit the program. The PushButton object for receiving data 



Figure 18.1 The Send Data program, placing data into a 
REXX external data queue. 
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Get Data by Ronny Richardson 


Line Humber 19: Random Number 8 
Line Number 28: Random Number 11 
Line Humber 21: Random Number 81 
Line Number 22: Random Number 31 
Line Number 23: Random Number 9 
Line Number 24: Random Number 98 


Figure 18.2 The Get Data program, reading data from a 
REXX external data queue. 


is disabled after it runs once. Its Click event, which is very similar to the Click event 
in Send Data, is as follows: 


Get_Click: 

Okay = VRSet("Get", "Enabled", 0) 

Line. = "" 

CALL RxQueue "Create","Ronny" 

CALL RxQueue "Set","Ronny" 

DO FOREVER 

DO J = 1 TO 6 
K = J + 1 
Line.J = Line.K 

END 

Info = Lineln("QUEUE:") 

IF Info = "TERMINATE" THEN RETURN 
Line.7 = Info 

Caption = Line.l !! "0d"x !! Line.2 !! "0d"x !! Line.3 

Caption = Caption !! "0d"x !! Line.4 !! "0d"x !! Line.5 
Caption = Caption !! "0d"x !! Line.6 !! "0d"x !! Line.7 
CALL LineOut "QUEUE:", Info 
Okay = VRSet("Text", "Caption", Caption) 

END 

return 


Figure 18.2 shows Get Data running. 


Queue 

Queue is a multithreaded demonstration program that immediately starts four 
threads to read data from four external data queues Ronny 1, Ronny2, Ronny3, and 
Ronny4. If any or all of these queues are in use, it will select its own names. The re¬ 
sults of these four threads are shown on the right side of the screen in separate De¬ 
scriptive Text objects. Initially, these displays show nothing as nothing has been 
placed in the external data queues. 







258 


Advanced VX-REXX Topics 


Four additional threads are under user control. They can be started from the 
menu or by using Ctrl-1 through Ctrl-4. Each of these threads sends data to one of 
the external data queues being read by the previous threads. The lines they place in 
their respective queues are shown in the Descriptive Text object on the left side of 
the screen. Each time one of these threads is invoked, 100 lines of data are placed 
into the queue. Since each Descriptive Text object is serviced by its own thread, all 
eight can be updated at once. Figure 18.3 shows Queue running with all four threads 
sending data, so all eight Descriptive Text objects are being updated by the program. 


Getting the Process Started 

Much of the work is handled in the Init subroutine. This is where the queues are cre¬ 
ated, the internal names of the Descriptive Text objects are read and stored to vari¬ 
ables so they can be used by the threads, and the four threads that read the external 
data queues are started. The relevant section of the Init subroutine is as follows, with 
line numbers added: 

1. Queuel = RxQueue("Create", "Ronnyl") 

2. Queue2 = RxQueue("Create", "Ronny2") 

3. Queue3 = RxQueue("Create", "Ronny3") 


Queue by Ronny Richardson 


Send data via queue Quit 


.!□ 
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Figure 18.3 The Queue program, placing data into four REXX external data queues and reading data from 
these same four queues—all at the same time. 
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4. Queue4 = RxQueue("Create", "Ronny4") 

5. SendlHandle = VRGet("Send_l", "Self") 

6. Send2Handle = VRGet("Send_2", "Self") 

7. Send3Handle = VRGet("Send_3", "Self") 

8. Send4Handle = VRGet("Send_4", "Self") 

9. ReceivelHandle = VRGet("Receive_l", "Self") 

10. Receive2Handle = VRGet("Receive_2", "Self") 

11. Receive3Handle = VRGet("Receive_3", "Self") 

12. Receive4Handle = VRGet("Receive_4", "Self") 

13. ReceiveThreadl=VRMethod("Application","StartThread","Receive", 

Queuel,ReceivelHandle) 

14. ReceiveThread2=VRMethod("Application","StartThread","Receive", 

Queue2,Receive2Handle) 

15. ReceiveThread3=VRMethod("Application","StartThread","Receive", 

Queue3,Receive3Handle) 

16. ReceiveThread4=VRMethod("Application","StartThread","Receive", 

Queue4,Receive4Handle) 

17. SendThreadl = "" 

18. SendThread2 = "" 

19. SendThread3 = "" 

20. SendThread4 = "" 

Lines 1-4 create the four queues. Since Queuel through Queue4 are used through¬ 
out the program as the queue names and not Ronnyl-Ronny4, the program auto¬ 
matically handles the problem of a queue name already being used. Lines 5-12 get 
the VX-REXX names for the Descriptive Text objects so they can be referenced in 
other files. Lines 13-16 start the threads that read the four queues. In the process, 
these lines pass the threads the name of the queue they’ll be reading and the name 
of the Descriptive Text object they’ll be updating. Lines 17-20 initialize the variables 
used to store the names of the sending threads. 

The four threads to send data to the external data queues are started individually 
by menu options. The code to start the first thread is: 


Sendl_Click: 

Okay = VRMethod("Application", "HaltThread", SendThreadl) 
SendThreadl = VRMethod("Application", "StartThread", "Sendl", 
Queuel, SendlHandle) 
return 


The second line halts this thread if it’s already running. The third line restarts the 
thread, passing it the name of the queue to use and the Descriptive Text object to 
update. 


The sending threads 

Each of the four threads for sending threads calls on the same file, passing it the 
name of the queue as the first argument and the name of the Descriptive Text object 
to update as the second argument. The code for this file is as follows, with line num¬ 
bers added: 


1. Main: 

2. Queue = Arg(1) 

3. DT = Arg(2) 

4. Line. = "" 
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5 . 

Okay = RxQueue("Set" , 

Queue) 



6. 

DO I = 1 TO 

100 




7 . 

Info = n : 

Line Number "I ! ! " 

: Random Number" RANDOM(1,100) 

8 . 

CALL LineOut "QUEUE:", Info 



9. 

Line.l = 

Line. 2 




10 . 

Line. 2 = 

Line. 3 




11. 

Line. 3 = 

Line. 4 




12 . 

Line. 4 = 

Line. 5 




13 . 

Line.5 = 

Line. 6 




14. 

Line. 6 = 

Line. 7 




15. 

Line. 7 = 

"Writing 

Line #" ! ! 

I "Of 100 

To Session " !! Arg(l) 

16. 

Caption 

= Line.l ! 

! "0d"x ! ! 

Line.2 ! ! 

" 0d"x ! ! Line . 3 

17 . 

Caption 

= Caption 

! ! "0d"x ! 

! Line.4 ! ! 

"0d"x I! Line.5 

18. 

Caption 

= Caption 

! ! "0d"x ! 

! Line.6 ! ! 

" 0d"x 1 ! Line . 7 

19 . 

Okay = VRSet(DT, 1 

'Caption", 

Caption) 


20. 

END 





21. 

return 






Lines 2-3 read in the arguments passed to the file. Line 4 resets a variable. Line 5 ac¬ 
tivates the appropriate queue. Line 6 begins a loop to send out 100 lines of data. Line 
7 creates the line of data, and line 8 writes it to the queue. Lines 9-14 move the lines 
of text used to display up one line for scrolling. Line 15 stores a new line of text to 
one of the variables used for display. Lines 16-18 create a caption for display, and 
line 19 displays that caption. Line 20 terminates the loop. 


The receiving threads 

The four receiving threads all call the same file. This file simply executes an endless 
loop that reads data from the queue and then displays it in a Descriptive Text object. 
When no data is available in the queue, this loop pauses on the line that reads the 
queue until data becomes available. This code is shown here, with line numbers 
added: 


1. 

Main: 




2 . 

Queue = Arg(1) 




3 . 

Okay = RxQueue("Set", Queue) 




4 . 

DT = Arg(2) 




5 . 

Line. = "" 




6. 

DO FOREVER 




7 . 

DO J = 1 TO 6 




8. 

n 

U| 

+ 

K 1 




9. 

Line.J = Line.K 




10. 

END 




11. 

Caption=Line.1 !! "0d"x !! 

Line.2 !! 

"0d"x !! Line.3 !! 

" 0d"x 

12 . 

Caption=Caption !! Line.4 

! : "0d"x ! ! 

Line.5 1! "0d"x ! 

! Line 

13 . 

ReadLine = Lineln("QUEUE:" 

) 



14 . 

Line.7 = ReadLine 




15. 

Caption = Caption !! "0d"x 

! ! Line.7 



16. 

Okay = VRSet(DT, "Caption" 

, Caption) 



17 . 

END 




18 . 

exit 





Line 2 reads the name of the queue, which is passed to the file as an argument, while 
line 3 activates that queue. Line 4 reads the name of the Descriptive Text object used 
to display the data that’s read. This is also passed to the program as an argument. 
Line 5 resets a variable. Line 6 starts a loop that continues forever. Lines 7-10 move 



Using the External Data Queue 261 


the lines of text used for display up one line for scrolling. Lines 11-12 create most of 
the caption. Line 13 reads a line from the queue, and lines 14-15 add it to the cap¬ 
tion. The thread won’t move past line 13 until data is available in the queue. Line 16 
displays the caption, and line 17 terminates the loop. 


Termination 

With all these threads running, the Quit subroutine has extra work to perform. It’s 
shown here, with line numbers added: 


1. 

Quit: 



2 . 

Okay = 

VRMethod("Application", 

"HaltThread 

3 . 

Okay = 

VRMethod("Application", 

"HaltThread 

4 . 

Okay = 

VRMethod("Application", 

"HaltThread 1 

5 . 

Okay = 

VRMethod("Application", 

"HaltThread 1 

6. 

Okay = 

VRMethod("Application", 

"HaltThread 1 

7 . 

Okay = 

VRMethod("Application", 

"HaltThread' 

8. 

Okay = 

VRMethod("Application", 

"HaltThread 1 

9. 

Okay = 

VRMethod("Application", 

"HaltThread 1 

10. 

window 

= VRWindow() 


11. 

call VRSet window, "Shutdown", 

1 

12 . 

drop window 


13 . 

return 




ReceiveThreadl) 
ReceiveThread2) 
ReceiveThread3) 
ReceiveThread4) 
SendThreadl) 
SendThread2) 
SendThread3) 
SendThread4) 


Lines 2-5 terminate the receiving threads and lines 6-9 terminate the sending 
threads. Lines 10-12 are a normal part of the Quit subroutine. 


Summary 


The external data queue is a powerful method for REXX programs to communicate 
with each other and for non-REXX programs to communicate with a REXX program. 
It’s particularly useful for a large volume of communication between an external sub¬ 
routine and calling program. VX-REXX programs can use the external data queue as 
easily as REXX. 

Send Data is a VX-REXX program that places data into the external data queue. 
Get Data is a VX-REXX program for reading data from the external data queue. 
Queue is a VX-REXX program that uses multiple threads to simultaneously read 
from and write to four external data queues. 
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Working with Configuration Files 


I do my writing with Describe for OS/2. When I start DeScribe, it automatically re¬ 
members the last eight files I’ve worked on. My backup program prompted me for my 
name and company when I installed it and it remembers and shows those each time 
it starts. Probably many of the programs you use remember information between 
sessions. We’ll explore adding this capability to VX-REXX programs in this chapter. 

You don’t really need any new tools to do this. One approach would be to just store 
the information in an ASCII file in the same subdirectory as the application. Your pro¬ 
gram would simply have to locate the drive and subdirectory it was started from, 
read in the values it finds there, and use them. That isn’t hard to do. The _VREPri- 
maryWindowPath variable contains the drive and full path to the program, and you 
can strip those off using the VRParseFileName function. After that, reading and us¬ 
ing the ASCII file is easy. Another way is to use the Program or WorkingDirectory 
property of the Application object. This second way is even better because Watcom 
could change the names of the variables it uses. 

This does, however, have a drawback. Since the file is an ASCII file, it’s easy for the 
user to load the file into the OS/2 Enhanced Editor and make changes without you 
being able to control and validate those edits. One of the games my kids used to play 
kept the high score and name of the player who made that score in an ASCII file. I 
was able to really impress them by editing the file and giving myself a very high 
score. They were much less impressed when I showed them the trick. 

Which Configuration File to Use? 

You might think that you face a real dilemma in getting started. After all, in order 
to read information from a configuration file, your program must first know where 
the configuration file is located. But before it knows where the configuration file 
is stored, it needs configuration information! There is, however, a solution. OS/2 
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maintains two configuration files that it always knows the path to. They are the 
system file, which is normally C:\OS2\OS2SYS.INI, and the user file, which is nor¬ 
mally C:\OS2\OS2.INI. 

Since VX-REXX can work with these two files, you have two choices; you can store 
all of your program’s configuration information in one of them or you can just store a 
pointer to your program’s own configuration file in one. 

If you use the former approach, all you have to do when your program starts is 
read the configuration information it expects from that file. If some or all the infor¬ 
mation is missing, your program can invoke an installation subroutine to supply the 
missing information. 

If you use the latter approach, your program will read the location of its own con¬ 
figuration file from one of these two files and then read its own configuration file to 
get the configuration information it expects. If the location of this file is missing or if 
information is missing from its own configuration file, your program could invoke an 
installation subroutine to supply what’s missing. 

Configuration Functions 

VX-REXX has three functions for working with configuration functions: VRDellni, 
VRGetlni, and VRSetlni. They were covered in Chapter 12, but I’ll review each of 
them here. 


VRDelini 

The VRDellni function allows you to delete a value from an .INI file. Its syntax is: 

Okay = VRDellni {application, keyword, [file], ["NoClose"]) 

where: 

* Application is the name of the application whose initialization file VRDellni is to 
operate on. This term is case-sensitive. 

■ Keyword is the specific value to be removed. This term is case-sensitive. 

« File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

■ NoClose is an option to keep the file open after this operation so more operations 
can be performed on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a 1 if it’s successful and a 0 if it fails. 

VRGetlni 

The VRGetlni function returns a setting from an .INI initialization file. Its syntax is: 


Setting = VRGetlni( application, keyword, [file], ["NoClose"]) 
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where: 

■ Application is the name of the application whose initialization file VRGetlni is to 
operate on. This term is case-sensitive. 

* Keyword is the specific value to be loaded. This term is case-sensitive. 

■ File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

■ NoClose is an option to keep the file open after this operation so more operations 
can be performed on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a string with the setting if it’s successful and a null string oth¬ 
erwise. 


VRSetlni 

The VRSetlni function inserts a setting into an .INI initialization file. Its syntax is: 

Okay = VRSetlni {application, keyword, value [file], ["NoClose"]) 


where: 

■ Application is the name of the application whose initialization file VRSetlni is to 
operate on. This term is case-sensitive. 

■ Keyword is the specific value to be set. This term is case-sensitive. 

* Value is the new value for keyword. 

" File is the name of the initialization file to process. The default is the OS/2 user file 
if none is specified. 

H NoClose is an option to keep the file open after this operation so more operations 
can be performed on the initialization file without having to reopen it. This speeds 
successive operation. 

The function returns a 1 if it’s successful and a 0 otherwise. 

Using Configuration Functions in a Program 

Ini is a sample program that stores the user’s first name, last name, and age in its 
own configuration file (INI.INI). Its purpose is to demonstrate the use of program 
configuration. 

Initializing the program 

The Init subroutine is shown following this paragraph. The last three lines of the sub¬ 
routine use the VRGetlni VX-REXX function to read the OS/2 user configuration file 
(it’s the default when a name isn’t specified) to get the location of the configuration 
file for Ini. 
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Init: 

window = VRWindow() 

call VRMethod window, "CenterWindow" 
call VRSet window, "Visible", 1 
call VRMethod window, "Activate" 
drop window 

IniSubdirectory = VRGetlni("INI.EXE", "IniSubdirectory") 

IF IniSubdirectory = "" THEN CALL Notlnstalled 
ELSE CALL Configured 
return 


When the Init subroutine doesn’t find a location for the Ini configuration file, it as¬ 
sumes that the program hasn’t been installed and calls the Notlnstalled subroutine. 
That subroutine is: 


Notlnstalled: 

Okay = VRMessage("Windowl", "Program Not Installed! 
"Install Warning", "W") 
return 


All this subroutine does is display a warning because the user expects to configure 
the program from the main window. In a more typical application, the Notlnstalled 
subroutine would handle getting and storing the installation options. 

The Configure PushButton pops up a dialog box in which the user enters the lo¬ 
cation of the configuration file for Ini (see Figure 19.1). Its code is as follows, with 
line numbers added: 


1. PB_Configure_Click: 

2. Button.0 = 2 

3. Button.1 = "Cancel" 

4. Button.2 = "OK" 

5. Okay = VRPrompt("Windowl", "Enter INI Subdirectory", 

"IniSubdirectory", "Configure", "Button.") 

6. IF Okay \= 2 THEN RETURN 

7. IniSubdirectory = VRParseFilePath(IniSubdirectory, "DP") !! "\" 

8. Okay = VRSetlni("INI.EXE", "IniSubdirectory", 

IniSubdirectory, "USER") 

9. Ini = IniSubdirectory !! "INI.INI" 

10. Okay = VRSet("DT_2", "Caption", IniSubdirectory) 

11. Okay = VRSet("PB_1", "Enabled", 1) 

12. return 


Lines 2-4 set up the buttons to be used and line 5 displays a dialog box to get the 
subdirectory from the user. If the program has already been configured, the dialog 
box is seeded with the old value. If the user doesn t click on the OK button, line 6 ex¬ 
its the configuration subroutine. Line 7 strips the drive and subdirectory from the in¬ 
formation entered by the user and line 8 stores it to the OS/2 user configuration file. 
Line 9 creates a variable containing the full path to the Ini configuration file. Line 10 
displays this in a Descriptive Text object and line 11 enables the PushButton object 
to delete the current configuration. 
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qI Inf by Runny Richardson 
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Figure 19.1 Using the Configure button of the Ini program to 
store the name and location of a new configuration file. 


Getting stored values 

When Ini is started after it has been configured, the Init subroutine calls the Config¬ 
ured subroutine to read the first name, last name, and age currently stored in the Ini 
configuration file. That code is as follows, with line numbers added: 


1. 

Configured: 



2. 

Store. 

1 = VRGet("EF_ 

1", "Change") 

3 . 

Store. 

2 = VRGet("EF_ 

2", "Change") 

4 . 

Okay = 

VRSet("EF_1", 

"Change", 

"") 

5. 

Okay = 

VRSet("EF_2", 

"Change", 

"") 

6. 

Okay = 

VRSet("DT_2", 

"Caption", 

, IniSubdirectory) 

7. 

Ini = 

IniSubdirectory !! "INI.INI" 

8 . 

Age = 

VRGetlni("INI. 

EXE", "Age' 

", Ini, "NoClose") 

9. 

Name = 

VRGetIni("INI 

.EXE", "Name", Ini) 

10 . 

Okay - 

VRSet( "EF_1" 

, "Value", 

Name ) 

11. 

Okay = 

VRSet( "EF_2" 

, "Value", 

Age ) 

12 . 

Okay = 

VRSet("EF_1", 

"Change", 

Store.1) 

13 . 

Okay = 

VRSet("EF_2", 

"Change", 

Store.2) 

14 . 

return 





Lines 2-3 store the code for the Change event for EF_1 and EF_2, while lines 4-5 
turn off the Change event. This allows values to be placed into these fields without 
triggering a Change event. Line 6 stores the Ini configuration subdirectory in a De¬ 
scriptive Text object. Line 7 creates a variable containing a full path to this file. Line 
8 reads the age from this configuration file and line 9 reads the name. Lines 10-11 
place these pieces of information in their respective EntryField objects, while lines 
12-13 restore the Change events. 
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Storing changes 

When the user clicks on the button to Save Changes to Configuration, the following 
subroutine writes the new values to the configuration file: 


PB_3_Click: 

Okay = VRSet("PB_3", Enabled, 0) 

Name = VRGet( "EF_1", "Value" ) 

Age = VRGet( "EF_2", "Value" ) 

Okay = VRSetIni("INI.EXE", "Age", Age, Ini) 
Okay = VRSetlni("INI.EXE", "Name", Name, Ini) 
return 


It also turns off the Save Changes to Configuration button because the values are 
now unchanged. Once one of these values is modified, the Click event for that En¬ 
try Field object enables this button again. 


Deleting configuration information 

While it would be unusual in a production program, Ini has a Delete Current Config¬ 
uration button to remove all configuration information. It’s similar to other code 
shown already, so it’s presented without comment below: 


PB_l_Click: 

Store.1 = VRGet("EF_1", "Change") 

Store.2 = VRGet("EF_2", "Change") 

Okay = VRSet("EF_1", "Change", "") 

Okay = VRSet("EF_2", "Change", "") 

Okay = VRDelIni("INI.EXE", "IniSubdirectory", "USER") 

Okay = VRSet("DT_2", "Caption", "") 

Okay = VRDelIni("INI.EXE", "Name", Ini) 

Okay = VRSet("EF_1", "Value", "") 

Okay = VRDelIni("INI.EXE", "Age", Ini) 

Okay = VRSet("EF_2", "Value", "") 

Okay = VRSet("PB_1", "Enabled", 0) 

Okay = VRSet("PB_3", "Enabled", 0) 

Okay = VRSet("EF_1", "Change", Store.1) 

Okay = VRSet("EF_2", "Change", Store.2) 
return 

Figure 19.2 shows the Ini program running after it has loaded existing configuration 
information. 


Summary 

Using a configuration file can make your programs look more professional. You can 
use the VX-REXX VRDellni function to erase configuration information, VRGetlni to 
extract configuration information, and VRSetlni to store configuration information. 
The Ini program demonstrates the use of configuration files. 
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Stores Default Subdirectory To QS2.IN1 
Current .INI Subdirectory 
e^os2\vxrexx\examples\ini\ 



Figure 19.2 The Ini program running. 
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Working with 
Dynamic Data Exchange 


Dynamic data exchange (DDE for short) is an OS/2 facility that allows two programs 
running under OS/2 to exchange data. This chapter will have to be just an introduc¬ 
tion to DDE. By its very nature, DDE involves VX-REXX communicating with an¬ 
other program—and a non-VX-REXX program at that because VX-REXX is unable to 
communicate with itself using DDE. The examples in this chapter will have VX- 
REXX communicate with the OS/2 versions of Describe and Lotus 1-2-3 for OS/2. 

When two programs communicate via DDE, they are engaged in what OS/2 calls a 
conversation. At any one time, one of the applications is the client and the other is 
the server. The client is the program sending out commands—typically requests for 
data—and the server is the program responding to those requests. A VX-REXX pro¬ 
gram can function only as a client, which is why VX-REXX can’t communicate with 
itself using DDE. 

All DDE conversations have a topic, which is the subject of the conversation. The 
topic must be defined when the client first connects to the server. When connecting 
to a word processor, for example, the topic could be a filename. For most of the ex¬ 
amples in this chapter, the topic will be a filename. All DDE servers support a topic 
called System for getting information about the server itself. 


Two Examples 

The purpose of DDE is to allow programs to share data. The following two exam¬ 
ples use the DDE sample program that comes with VX-REXX. In the first, the 
DDE sample program connects to DeScribe, loads a file, and gets a word count 
from that file. In the second, the program inserts a number into a Lotus spread¬ 
sheet. 
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Describe 

The first step is to connect to DeScribe. If DeScribe already has the file open you 
want to connect to, you can connect directly. For this example, however, we’ll con¬ 
nect to the System topic and then have DeScribe open a particular file. Figure 20.1 
shows using the DDE sample program to connect to DeScribe using the System 
topic. The DDEClient object in the sample program responds by displaying the name 
of the current conversation (see Figure 20.2). 

The next step is to tell DeScribe to open a file. In this example, we’ll use the 
D:\BOOK12\CHAPTE01.DOC file. DeScribe expects a WM_DDE_EXECUTE mes¬ 
sages containing one or more commands. Each command must be enclosed in 
square brackets, and all the commands except Open expect a filename as a parame¬ 
ter. The filename must be enclosed in quotation marks and parentheses, and follow 
the message name immediately without a space. The five commands DeScribe will 
accept in a WM_DDE_EXECUTE message are: 

New Window(“”). This opens a new DeScribe document. 

Open(“G:\directory\documenr). This opens the specified document. 



i Connections 


tf 1 ) DDE fes' 

Hal 1 

36 convers; 

Choose a DDE connection... 



DeScribe,D:\B00K13\CHAP-20.DOC 
DeScribe,D:\B00K13\SECTION2.DOC 
DeScribe,D:\BOOK13\PROGRAMS.DOC 
DeScribe,D:\B00K13\APPEND-A.DOC 
DeScribe,D:\BQOK 13\APPEND-B.DOC 

DeScribe,D:\B00K13\APPEND-C.DOC 
DeScribe,D:\B00K13\APPEMD-D.DOC 
DeScribe,D:\B00K13\HINTS.DOC 
DeScribe,D:\BQOK 13\GLOSSARY.DOC 

* 

T 


Connect 

oke 


1 Describe,bystem 






Figure 20.1 Using the DDE sample program that comes with VX-REXX to connect 
to DeScribe via DDE using the System topic. 


Conversing with application ’Describe’, topic ’System’ 


Connect I Terminate | Execute h Request j Poke 


Figure 20.2 The DDE object in the DDE sample program responds by giving the name 
of the current conversation. 
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Figure 20.3 Using DDE to tell DeScribe to open D:\BOOK12\CHAPTE01.DOC. This is 
a DeScribe command and not a VX-REXX command. 



Figure 20.4 Using DDE to tell DeScribe to run a macro in D:\BOOK12\CHAPTE01 .DOC. 
This is a DeScribe command, not a VX-REXX command. 


Pfm\(“C-\directory\document’). This prints the specified document. If the file isn’t 
open, DeScribe will open it, print it, and then close it. If it’s already open, DeScribe 
will just print it. 

Run(“macro”). This runs the specified macro. A path isn’t required because De¬ 
scribe keeps its macros in a common subdirectory and it knows the path to that sub¬ 
directory. 

Close(“C:\directory\documenf’). This closes the specified file. If you’re working in 
DeScribe and try to close a file that has been modified since the last time you saved 
it, DeScribe will warn you first and give you a chance to save it. When responding to 
a DDE command, DeScribe assumes the client knows what it’s doing and will close a 
file without warning if it has been modified since its last save. 

Figure 20.3 shows using the DDE sample program to tell DeScribe to open the 
D:\BOOK12\CHAPTE01.DOC file. Opening a file doesn’t automatically connect you 
to that file, so the DDE sample program in this example remains connected to the 
System topic. You don’t need to open any other files, so you can now connect to the 
D:\BOOK12\CHAPTE01.DOC topic. 

The next step is to run a DeScribe macro to count the number of words in the file. 
As Figure 20.4 shows, this is a simple task using the Run command. The real trick, 
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however, is in the WC macro that DeScribe executes. This macro is a slight modifi¬ 
cation of a macro written by Steve Weeks, and it’s as follows: 

MACRO DeScribeMacro 

SET LinkTagName TO "WordsCount" 

IF LinkTagExists THEN 

DeleteLinkTag "WordsCount" 

ELSE 
END IF 
CursorHome 
SET A TO 0 
REPEAT 

CursorWordRight 
SET A TO A+l 
EXIT WHEN EndOfFrame 
END REPEAT 

SET B TO NumberFrameLines 
SET A TO A-B 
PUT A 

DefineToWordBegin 
CreateLinkTag "WordsCount" 

END MACRO 

This isn’t a book on DeScribe macros, so I won’t go over it in detail. I will, however, 
provide an overview to give you an idea of what it’s doing. WC works by counting the 
number of times the REPEAT instruction is executed and then subtracting the num¬ 
ber of lines in the document. The number of lines is subtracted because each line re¬ 
quires an additional right cursor movement and is therefore treated as a “false” word 
by the macro. After it reaches the end of the file, it inserts the contents of the A vari¬ 
able into the file and creates a tag called WordsCount. In order for this to work prop¬ 
erly, the file must have a blank line at the end. 

Of course, this modifies the file. Once the information is read, you can simply close 
the file to discard the change. You can also run the WC-GONE macro to strip off the 
word-count information. WC-GONE is included in the \EXAMPLES\WC subdirectory 
of the CD-ROM that comes with this book. 

Once the WC macro creates this tag, the DDE sample program can request that in¬ 
formation simply by sending the WordsCount name to DeScribe. Figure 20.5 shows 
the results and, as you can see, D:\BOOK12\CHAPTE01.DOC has 8,245 words. Keep 
in mind that this is an approximate count and might be slightly different than the 
number DeScribe provides using the Statistics command on its File menu. 

The WC macro takes a significant amount of time to run, especially on a longer file 
like D:\BOOK12\CHAPTE01.DOC. The WordsCount data isn’t available to the DDE 
sample program until the macro has finished running, but the DDE sample program 
has no way of knowing when the WC macro finishes. Here, if you get a blank response, 
you can just try again in a few seconds. However, you’ll see this problem again. 

Lotus 1-2-3 for OS/2 

Begin by loading a blank worksheet into Lotus 1-2-3 for OS/2 and giving it the name 
DDE_TRY.WG2. The next step is to have the DDE sample program connect to 
DDE_TRY.WG2. Once again, the DDEClient object in the DDE sample program dis¬ 
plays information on the conversation, as Figure 20.6 shows. 
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Figure 20.5 The DDE program displaying the contents of the Wordscount tag. This 
shows that D:\BOOK12\CHAPTE01.DOC has 8,245 words. 



Conversing with application "Lotus 1 , topic , DDE_TRY.WG2' 


Connect j 

Terminate 

Execute 

Request j 

Poke 


Figure 20.6 The DDE object in the DDE program again displays the name of the con¬ 
versation. 


d=| DDE 1 

"psUirwi 

■J “MI 

Convers 



Item: B1 


Data: 100 ; 

Poke 

1 f;nnni 


a 

j | §[ | [ » 1 | 

1 


Figure 20.7 Using DDE to poke the value of 100 into cell B1 of DDE_TRY.WG2. 


This time, rather than taking information (Wordscount) out of the server, 
you’re going to poke information into the server. For Lotus, the item will be the 
cell address, B1 in this example, and the data will be the contents to put into that 
cell, 100 in this example. Figure 20.7 shows the DDE sample program poking this 
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data into DDE_TRY.WG2. After this, seven more pieces of data are poked into the 
worksheet in cells At through B4. Figure 20.8 shows the resulting worksheet. 

DDE in VX-REXX 

You can make a VX-REXX program a DDE client by adding a DDEClient object to the 
program. The DDEClient object automatically updates its caption to describe the cur¬ 
rent DDE conversation. If you want to hide that from the user, you can make the 
DDEClient object invisible once you’re finished debugging your program and are sure 
it’s working properly. A DDEClient object in a VX-REXX program can perform the fol¬ 
lowing actions: 

Start a conversation, A DDEClient object can participate in only one conversation 
at a time. You initiate a conversation using both the Initiate and Accept methods. 
The Initiate method constructs a stem variable with a list of available servers and 
topics. You can place limits on the available servers or topics to add to the list if you 
like. Once the list is developed, the Accept method actually starts the conversation. 

Send commands to server. The Execute method sends commands to the server for 
execution. As you’ve seen already, the syntax of these commands depends on the 
server. 

Request data. The Request (for a single request) and the RequestList (for a list of 
requests) methods send requests for data to the server. Your VX-REXX program 
(the client) must send a request for data; it can’t just accept data the server chooses 
to send. You can set up an automatic link with a DDE data source, in which case the 
source notifies you if its data changes. 



Figure 20.8 The DDE_TRY.WG2 worksheet after four data points and four la¬ 
bels have been poked in. 
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Send data. The Poke method sends data to the server. Each Poke requires an item 
name and a value to send. The acceptable item names depend on the server. 

Find conversation status. The DDEClient object has three properties—Status, 
Server, and Topic—that can be retrieved with the VRGet VX-REXX function. The 
Status property indicates if the conversation is still active, the Server property stores 
the name of the server, and the Topic property stores the topic of the conversation. 

Terminate a conversation. The Terminate method terminates a conversation. You 
can also terminate a conversation by starting a new conversation or destroying the 
DDEClient object. 

Two Examples 

We’ll look at two VX-REXX examples: WC and WC-BOOK. Both of these count the 
words of one or more Describe documents using the WC and WC-GONE macros. 


WC is a demonstration program that prompts you for the name of a DeScribe docu¬ 
ment and then reports the number of words in that file. DeScribe must be running 
without the requested file loaded in order for WC to work. In addition, both WC and 
WC-GONE must be installed in the DeScribe macro subdirectory for WC to work. 
These macros are included in the \EXAMPLES\WC subdirectory along with the WC 
program. 

The user interface for WC consists of a DDEClient object, a Descriptive Text ob¬ 
ject for displaying results, a PushButton object to start the program, and another 
PushButton object to exit the program. The bulk of the program’s work is done by 
the Click event for the Start PushButton object. This important subroutine is ex¬ 
plained in detail in Figure 20.9. 

The first thing WC does is ask for the name of the DeScribe file to process. As WC 
runs, the DDEClient object keeps the user updated on the DDE conversation. Fi¬ 
nally, the program shows the results, as shown in Figure 20.10. 

You don’t need VX-REXX to accomplish much of what WC does. The WC-LOTUS 
DeScribe macro, following, will perform a word count on the current document and 
use DDE to post the results to cell A1 of DDE_TRY.WG2. This macro is also included 
in the \EXAMPLES\WC subdirectory of the CD-ROM that comes with this book. 


MACRO DeScribeMacro 

SET LinkTagName TO "WordsCount" 
IF LinkTagExists THEN 

DeleteLinkTag "WordsCount" 
ELSE 
END IF 
CursorHome 
SET A TO 0 
REPEAT 

CursorWordRight 
SET A TO A+l 
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VX-Rexx Command 

Explanation 

PB__Start_Click : 

This is the subroutine that runs 

when the user clicks on the Start 
PushButton object. 

File = VRFileDialog ( VRWindow () , "Pick 

Document For Wordcount", "Open") 

Display a dialog box and ask the 
user to pick a file. This is the 
file that will be processed by the 
program. 

IF File = "" THEN RETURN 

If the user presses Escape or 
clicks on Cancel and so does not 
pick a file, return to the main 

screen. 

Okay = VRSet ( "DT_1", "Caption", File) 

Display the name of the file that 
was picked in a Descriptive Text 
object. 

Okay = VRMethod("DDEC_1", "Initiate", 
"Files.", "Describe") 

The Initiate method is used to 
fill a stem variable with avail¬ 
able DeScribe conversations. 

Okay = VRMethod("DDEC_1", "Accept") 

The Accept method defaults to 
using the first conversation 
found by the Initiate method if 
one is not specified. Since 
DeScribe will be instructed to 
open the appropriate file, any 
DeScribe conversation is accept¬ 
able. 

Okay = VRMethod("DDEC_1", "Execute", 

'[OPEN (" 'File' ")]') 

The Execute method sends the 
DeScribe t [OPEN( t “File’ , ‘)r 
command to DeScribe. This tells 
DeScribe to open the file select¬ 
ed above. 

Okay = VRMethod ( "DDEC_1 " , "Terminate") 

The Terminate method termi¬ 
nates the current DDE conversa¬ 
tion. 

Okay - VRMethod ( "DDEC_1", "Initiate", 
"Files.", "Describe", File) 

The Initiate method is used to 
fill a stem variable with the list 
of available DeScribe conversa¬ 
tions. Since the filename is spec¬ 
ified, only one conversation will 
be found, the conversation with 
the file the program wants to 
connect with. 

Okay = VRMethod ( "DDEC_1 " , "Accept") 

The Accept method accepts the 
first and only conversation, the 
one with the file the program 
wants to connect to. 

Okay = VRMethod ( "DDEC_1 " , "Execute", 

' [RUN("WC" )]') 

The Execute method sends the 
DeScribe ‘[RUN(“WC”);|’ 
command to DeScribe. This 
tells DeScribe to run the WC 

macro. 


Figure 20.9 The PC_Start_Click subroutine of the WC program. 
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Explanation 

Continue = "YES" 

DO WHILE Continue = "YES" 

The Continue flag variable con¬ 
trols how long the program stays 
in a DO WHILE loop. 

Count = VRMethod("DDEC_1", "Request", 
"Wordscount" ) 

Request the Wordscount vari¬ 
able from the current DDE con¬ 
servation. 

Number = Datatype(Count, "Number") 

Check to see if a number was 

returned. 

IF Number = 1 THEN Continue = "NO" 

If it was, set the flag variable to 
terminate the loop. Otherwise, 
the program will continue loop¬ 
ing. This is required because the 
program has no other way of 
determining when the WC 
macro is finished. 

END 


Okay = VRSet("DT_1", "Caption", Count "Words 
In" File) 

Display the word count in a 
Descriptive Text object. 

Okay = VRMethod("DDEC_1", "Execute", 

' [RUN("WC-GONE" )]') 

The Execute method sends the 
Describe 4 [RUN(‘WC- 
GONE”)]’ command to 

DeScribe. This tells DeScribe to 
run the WC-GONE macro. 

Okay = VRMethod ( "DDEC_1 " , "Execute", 

' [CLOSE (" 'File' ")] ' ) 

Send DeScribe a command to 
close the file. 

Okay = VRMethod ( "DDEC_1 " , "Terminate") 

The Terminate method termi¬ 
nates the current DDE conversa¬ 
tion. 

return 

Exit the subroutine. 


Figure 20.9 Continued. 


1 Word Count by Ronny Richardson _J 


No conversation active. 


8245 Words in D:\BOOK12\CHAPTE01.DOC 


Start Word Count 


Quit Program 


Figure 20.10 Once the WC macro is finished, the WC program 
gives the user the word count. 
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EXIT WHEN EndOfFrame 
END REPEAT 

SET B TO NumberFrameLines 
SET A TO A-B 
PUT A 

DefineToWordBegin 

SET LinkDirectionExport TO TRUE 

CreateLinkTag "WordsCount" 

CreateAutomaticLink 11 Lotus ; DDE_TRY. WG2 ; A: Al; WordsCount 
DeleteLinkTag "WordsCount" 

DefineToWordEnd 
DeleteText 
END MACRO 


WC-Book 

WC-Book is a demonstration program that counts the number of words in a number 
of files. As each file is processed, the results are posted to the D:\BOOK13\WORD- 
COUN.WK3 Lotus worksheet. WC-Book requires the WC and WC-GONE DeScribe 
macros. 

The interface consists of one DDEClient object to handle the DDE interactions, 
two Descriptive Text objects the program uses for displaying messages to the 
user, and two PushButton objects—one to start the program and another to exit 
the program. 

The start PushButton object simply issues a CALL DoBook command. The Do- 
Book subroutine is: 


DoBook: 

Okay = VRSet("PB_Start", "Enabled", 0) 

Okay = VRSet("PB_Quit", "Enabled", 0) 

CALL Process "D:\BOOK13\PREFACE.DOC", B9 
CALL Process "D:\BOOKl3\ACKNOWLE.DOC", B8 
CALL Process "D:\BOOKl3\INTRO.DOC", BIO 
CALL Process "D:\BOOKl3\SECTIONl.DOC", Bll 
CALL Process "D:\BOOK13\CHAP-01.DOC", B13 
CALL Process "D:\BOOK13\CHAP-02.DOC", B14 

CALL Process "D:\BOOKl3\APPEND-C.DOC", B40 
CALL Process "D:\BOOK13\APPEND-D.DOC", B41 
CALL Process "D:\BOOKl3\HINTS.DOC", B36 
CALL Process "D:\BOOKl3\GLOSSARY.DOC", B37 
Okay = VRSet("PB_Start", "Enabled", 1) 

Okay = VRSet("PB_Quit", "Enabled", 1) 

Okay = VRSet("DT_1", "Caption", "Finished") 

Okay = VRSet("DT_2", "Caption", "Final Running Total Was: 
RunningTotal) 
return 


The subroutine begins by disabling the two PushButton objects. Then it calls the 
Process subroutine once for each file, and passes Process the name of the file to 
process and the cell address of where to insert the word count. It finishes by reen¬ 
abling the two PushButton objects. The bulk of the processing is performed in the 
Process subdirectory. This is explained in detail in Figure 20.11. 
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VX-Rexx Command 

Explanation 

Process : 

This subroutine processes each 

file as it receives the command 
from the DoBook subroutine. 

PROCEDURE EXPOSE WordCount. RunningTotal 

Hide all the variables except the 
WordCount stem variable and 
the RunningTotal variable. 

File = Arg(l) 

Receive the name of the file to 
process as the first argument. 

Cell = Arg(2) 

Receive the cell number to place 
the word count into as the sec¬ 
ond argument. 

Okay = VRSet ( "DT_1", "Caption", File) 

Display the name of the file 
being processed in a Descriptive 
Text object. 

Okay P VRMethod ( "DDEC_1 " , "Initiate", 
"Files.", "Describe") 

The Initiate method is used to 
fill a stem variable with avail¬ 
able DeScribe conversations. 

Okay = VRMethod("DDEC_1", "Accept") 

The Accept method defaults to 
using the first conversation 
found by the Initiate method if 
one is not specified. Since 
DeScribe will be instructed to 
open the appropriate file, any 
DeScribe conversation is accept¬ 
able. 

Okay = VRMethod("DDEC_1", "Execute", 

'[OPEN("'File'") ]') 

The Execute method sends the 
DeScribe ‘[OPEN(“‘File’”)]’ 
command to DeScribe. This tells 
DeScribe to open the file select¬ 
ed above. 

Okay = VRMethod ( "DDEC_1", "Terminate") 

The Terminate method termi¬ 
nates the current DDE conversa¬ 
tion. 

Okay = VRMethod ( "DDEC_1 " , "Initiate", 
"Files.", "Describe", File) 

The Initiate method is used to 
fill a stem variable with the list 
of available DeScribe conversa¬ 
tions. Since the filename is 
specified, only one conversation 
will be found, the conversation 
with the file the program wants 
to connect with. 

Okay = VRMethod ( "DDEC_1", "Accept" ) 

The Accept method accepts the 
first and only conversation, the 
one with the file the program 
wants to connect to. 

Okay = VRMethod ( "DDEC_1", "Execute", 

' [RUN ( "WC" )]') 

The Execute method sends the 
DeScribe ‘[RUN(“WC”)]’ 
command to DeScribe. This 
tells DeScribe to run the WC 

macro. 


Figure 20.11 The Process subroutine, which performs the bulk of the work in the WC-Book program. 
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VX-Rexx Command 

Explanation 

Continue = "YES" 

DO WHILE Continue = "YES" 

The Continue flag variable con¬ 
trols how long the program stays 
in a DO WHILE loop.^ 

Count = VRMethod("DDEC_1", "Request", 
"Wordscount") 

Request the Wordscount vari¬ 
able from the current DDE con¬ 
versation. 

Number = Datatype(Count, "Number") 

Check to see if a number was 
returned. 

IF Number = 1 THEN Continue = "NO" 

If it was, set the flag variable to 
terminate the loop. Otherwise, 
the program will continue loop¬ 
ing. This is required because the 
program has no other way of 
determining when the WC 
macro is finished. 

END 

End of the DO WHILE 

Continue = “YES” loop. 

RunningTotal = RunningTotal + Count 

Keep a running total of the num¬ 
ber of words in all the files. 

Okay = VRSet("DT_1", "Caption", "") 

Reset the caption in the first 
Descriptive Text object. This 
signals that words are no longer 
being counted in the current file. 

Okay = VRSet("DT_2", "Caption", Count "Words 
In" File ", Running Total Is" 

RunningTotal "Words") 

Display the running total in the 
second Descriptive Text object. 

Okay = VRMethod("DDEC_1 " , "Execute", 

'[RUN("WC-GONE" )]') 

The Execute method sends the 
Describe ‘[RUN(“‘WC- 
GONE”) ]’ command to 

DeScribe. This tells DeScribe to 
run the WC-GONE macro. 

CALL Delay 

The WC program was process¬ 
ing only one file at a time so it 
did not have problems with 
“collisions.” DeScribe will 
queue the CLOSE command 
that follows until the WC- 
GONE macro finishes. If this 
program then tries to start WC 
on the next program before WC- 
GONE finishes, DeScribe 
responds with an error message 
asking if you want to stop the 
WC-GONE macro. This calls a 
processing loop that simply per¬ 
forms a series of calculations to 
delay the program long enough 
for the WC-GONE macro to fin¬ 
ish. 


Figure 20.11 Continued. 
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VX-Rexx Command 

Explanation 

Okay = VRMethod(”DDEC_1", "Execute", 

' [CLOSE (" 'File' ")]'.} 

Send DeScribe a command to 
close the file. 

Okay = VRMethod ( "DDEC__1" , "Terminate") 

The Terminate method termi¬ 
nates the current DDE conversa¬ 
tion. 

CALL AddToLotus 

Call a subroutine to insert the 
calculated word count into the 
spreadsheet. It has access to all 
the variables from this subrou¬ 
tine, so no arguments are 
required. 

return 

Exit the subroutine. 


Figure 20.11 Continued. 


Summary 

This chapter provides a brief introduction to OS/2 dynamic data exchange. It shows 
how to use the VX-REXX DDE sample program to load files and run macros in De- 
Scribe and how to insert values into a Lotus worksheet. It also shows how^ to have a 
DeScribe macro count words and insert that information directly into a Lotus work¬ 
sheet. 

The WC program prompts the user for a DeScribe document and counts the words 
in that document. The WC-Book program counts the words in a number of files. 






Chapter 

21 

Debugging VX-REXX Programs 


I hate debugging! Trying to figure out how to write a program to attack a particular 
problem is fun, and writing the program itself is partially work but it’s still very en¬ 
joyable. But figuring out why the program displays 17 when the correct result is 
clearly 19 is a pain. 

Programming bugs fall into two very broad categories: those bugs that will stop 
the execution of a program and those bugs that allow the program to continue to 
run. Those in the first category are the easiest to spot and resolve. Those in the sec¬ 
ond can be the tough ones to find because you never know what in the program is 
causing the problem. 

We’ll use the Debug Example program, stored in the \EXAMPLES\DEBUG subdi¬ 
rectory, in this chapter. Debug Example (DE for short) consists of a Descriptive Text 
object for displaying results and a menu with two options: one for starting a demon¬ 
stration and the other for stopping the program. The menu option to run a demon¬ 
stration runs the WorkingCode subroutine, shown here: 


WorkingCode: 

Do I = 0 TO 9 

DO J = 0 TO 9 
DO K = 0 TO 9 

DO L = 0 TO 9 

IF (1 = 0) Sc (J = 0) & (K = 0) THEN Text m L 

ELSE IF (1 = 0) Sc (J = 0) THEN Text = K i! L 

ELSE IF (I = 0) THEN Text = J !! K !! L 

ELSE Text = I ! ! ", " ! ! J ! ! K ! ! L 

Okay = VRSet("DT_1", "Caption", Text) 

END 

END 

END 

END 

return 
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This code displays the numbers 0 to 9,999 in the Descriptive Text object. As is, the 
code is bug-free, but not for long. Figure 21.1 shows the user interface for DE. You’ll 
see later why the program is so small. 

The Error Window 

When VX-REXX encounters a syntax error or other bug that’s too serious for the 
program to continue operation, the program aborts and displays an error window. 
For example, if you change the CALL WorkingCode command in the menu of DE to 
DO WorkingCode, you’ll get the error window shown in Figure 21.2. 

The first line of the error window is the Error field, which displays the REXX or 
VX-REXX error message. Below that is the Section field, which displays the name of 


ff | VX-REXX — debug (C:\OS2WXREXX\EXAM ; ° □ 

Project Jools Windows Run Options Help 


Figure 21.1 The Debug Example user interface. Note how small it is. It was designed this way so 
more of the interactive debugger windows would show on the screen. 
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Line 3 of Start^CUck in debug.VRM: 


I +++ Do WorkingCode; 

Line 47 of Main in debug.VRM: 

+++ Cali Start_Click; 

Line 47 of Main in debug.VRM: 

+++ Interpret _VREEvent; 

" □ 


jOpenl 


External editor 


Figure 21.2 Changing the CALL WorkingCode command in the 
menu Click event to DO WorkingCode brings up the error win¬ 
dow when the user clicks on the menu. 
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[gfj VX-REXX Console ~ 

hi 

3| 


SYS1041: The name specified is not recognized as an 
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Figure 21.3 Not all bugs will stop your program, as illustrated by including an invalid ESLE com¬ 
mand in the WorkingCode subroutine. 


the subroutine where the subroutine finally failed. Below that is the Traceback field. 
This field consists of several pairs of lines. For each pair, the top line displays a line 
number, subroutine name, and filename. The bottom line in the pair shows the 
REXX code associated with the error. The top pair references the line where the pro¬ 
gram finally failed, the next pair references the line that called the subroutine that 
failed, the next pair references the line that called the subroutine that called the sub¬ 
routine that failed, and so on until you reach the top level of the program. 

You can edit any of the subroutines by double-clicking on the code line in the er¬ 
ror window or highlighting the error line and selecting Open or External Editor from 
the menu. Once you fix the error, you must restart the program because VX-REXX 
isn’t able to pick up where it left off unless you use the interactive debugger. If an¬ 
other error occurs, VX-REXX will display only information regarding that error in 
the error window; information on prior errors is removed. 

The Interactive Debugger 

Not all bugs will stop your program. For example, insert a nonexistent ESLE com¬ 
mand into the WorkingCode subroutine of DE and you’ll end up with a display like 
Figure 21.3, but the program will continue running and adding more lines to the dis¬ 
play as it continually encounters the ESLE command in the loop. That is because 
REXX assumes that any command it doesn’t recognize should be passed on to the 
operating system for execution. Bugs like this can be much harder to find. Make a 
mistake in a complex mathematical formula and you’ll see the invalid number in a re¬ 
port, but you’ll have a hard time tracking down the errant formula. 

Even when a bug does stop your program, it doesn’t always stop your program on 
the line containing the bug. For example, a program might abort on the line Aver- 
age=Total/Count because the Count variable equals zero, but you’ll have to trace 
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through the entire program looking for the point where the Count variable was inap¬ 
propriately set to zero. 

When you’re on the trail of complicated, hard-to-find bugs, you need the interac¬ 
tive debugger that comes with VX-REXX. Unlike a program in REXX, a VX-REXX 
program needs no preparation before you use the interactive debugger. To start the 
interactive debugger, just select Debug Project from the Run menu rather than Run 
Project. 

The interactive debugger prepares the program for execution, but doesn’t start 
the program. It has four windows: the section list window, source window, variable 
display window, and results window. 


Section list 

The section list, shown in Figure 21.4 for DE, displays all the files in the project. For 
the currently selected file, it lists all the sections in that file. There can be only one 
copy of the section list. You use the section list to control the other windows. 


Source window 

The source window, shown in Figure 21.5 for DE, displays the source code for a par¬ 
ticular section. You obtain this window by double-clicking on a section of interest in 
the section list. You may have as many different source windows open as you like. 

You can select the variables to display by double-clicking on them in the source 
window, and set breakpoints in this window by double-clicking on the line number 
for the statement you want to be a breakpoint. A breakpoint is a place in the pro¬ 
gram where program execution pauses so you can use the debugger. Program exe¬ 
cution will pause after the line configured to be a breakpoint. Programs can have 
multiple breakpoints. 


Variable window 

The variable list, shown in Figure 21.6 for DE, displays the names and values of the 
variables selected for display in the source window. The value of these variables is 


ectipn list - DEBUG 


Run Windows Help 


□ 


Section List 

Fini 

Halt 

Init 

Main 

Quit 

Quite_Click 

Start_Click 

Window1_Close 


Figure 21.4 The interactive debugger section list win¬ 
dow with DE loaded. 
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Figure 21.5 The interactive debugger source window with DE loaded. 
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Figure 21.6 The interactive 
debugger variable window with 
DE loaded. 


updated only when control is returned to the interactive debugger, so their value 
isn’t continually updated. Control typically returns to the interactive debugger when 
the program hits a breakpoint. While the program waits on the interactive debugger, 
you can alter the contents of these variables and, when the program resumes execu¬ 
tion, it will use the new values you entered. You must press Return after entering a 
new value for that value to take effect. 


Result window 

The result window, shown in Figure 21.7 for DE, displays information on the REXX 
language. You can get any or all of three types of information: the source code state¬ 
ment being executed, the results of that execution, and REXX trace messages. 

Note that there’s an entry field at the bottom of the result window. While your pro¬ 
gram pauses, you can enter any standard REXX command, such as SAY 100 * 100, in 
this entry field and it will be executed and the results shown in the result window. 

Using the Interactive Debugger 

When you start your program with the interactive debugger, your program doesn’t 
initially run. This gives you time to position your windows, set breakpoints, and se- 
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Figure 21.7 The interactive debugger results window with DE loaded. 
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Figure 21.8 DE running in the interactive debugger environment. 


lect the variables you want to monitor. Once you’re ready, start your program by se- 
lecting Run from the Run menu. 

Your program will run normally, as Figure 21.8 shows, until it hits a breakpoint. 
When your program is suspended at a breakpoint, you can perform all the functions 
you performed before the program started. You can also change the contents of any 
of the displayed variables. To change the contents of a variable, just alter its value in 
the variable window. Be sure to press Return in that cell after changing a value so the 
new value will be recognized. 
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Tracing 


Once a program has stopped running, either because it reached a breakpoint or be¬ 
cause you selected Break from the Run menu, you can switch to tracing mode. To do 
this, select Step from the Run menu. This will cause the program to execute one line 
of code and then update the variable window. Each time you select Step from the 
menu or press the I key, one more line will be executed. This is a good way to narrow 
your problem down to a specific line when you know the general area of the bug, but 
are unsure of its exact location. 

If you want to run a particular line again, perhaps to see how it will execute with a 
new value, select Redo rather than Step from the Run menu and the last line will be 
executed over again. If the program is ready to call a subroutine that you know works 
properly, select Step Over from the Run menu to execute that subroutine without 
stopping. Tracing will resume when the subroutine is finished. You can resume nor¬ 
mal execution by selecting Run from the Run menu. 

Stopping the Interactive Debugger 

If you want to stop a program while it’s running, select Break from the Run menu. If 
you want to terminate the entire interactive debugger session, then close the section 
list window. This will terminate the entire session and return you to the VX-REXX 
design environment. If your program is running at the time, VX-REXX will stop it just 
as if you had selected Break from the Run menu. Should your program encounter an 
error, the interactive debugger will terminate and return you to the VX-REXX design 
environment with the error window showing, just as though the error had occurred 
outside the interactive debugger. 

As a general rule, you’ll know which section of code is causing your problems, ei¬ 
ther because the error window points you to that code or because you’ve had prob¬ 
lems with a value that’s created or modified in that section. When this happens, I’ve 
found that a good, old-fashioned way to figure out exactly where the problem lies is 
to insert a series of REXX Say commands into the code in the problem section. 
These cause a standard input/output (STDIO) window to be opened behind your 
program where all the results of the Say command are written. 

The STDIO window is a scrollable window, so you can scroll back through all the 
lines looking for the problem. You can even use the multitasking abilities of OS/2 to 
switch to this window and scroll through its output while your program continues to 
run. While not as fancy as the interactive debugger, it’s often a quick way to spot the 
problem. The Trace R and Trace ?R installations are also handy ways to debug the 
old-fashioned way. 


Summary 

This chapter shows you how to use the error window to display the section of code 
that caused your program to bomb, and trace that section back to the subroutines 
that called it. It also shows how to use the interactive debugger to find errors. Finally, 
it explains how to use the REXX Say command to find errors. The Debug Example 
program simulates bugs. 




Chapter 

22 

VX-REXX Summaries 


This chapter presents three tables that list all the VX-REXX objects across the top of 
the table, and the events, methods, or properties down the left side. The left page 
defines the event, method, or property and the right page indicates which object or 
objects possess that event, method, or property. 

An event occurs when the user does something to an object, for example, clicking 
on it or setting it. When the user does something to an object that generates an 
event, VX-REXX executes a special subroutine that’s associated with that event, 
called an event routine. 

An event happens because a user does something to an object. When VX-REXX it¬ 
self does something to an object, it uses a method. A method is a built-in operation 
that allows VX-REXX to modify the object. For example, the Maximize method 
makes a Window object as large as possible. 

The characteristics of an object that determine how it looks and behaves are called 
its properties. When an object is first created, VX-REXX gives it default properties. 
Some of these, such as the basic function of the object, can’t be changed, but most 
properties can be changed. You can change them at design time with the object’s 
property notebook or at runtime with VX-REXX functions. A few properties, such as 
Name, are possessed by every object, but most properties are owned by only a lim¬ 
ited number of objects. 
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Events 

Event 

Activate 

BeginEdit 

Change 

Click 

Close 

CollapseTree 

ContextMenu 

Create 

Deactivate 

Destroy 

Doubleclick 

DragDiscard 

DragDrop 

DragPrint 

EndEdit 

ExpandTree 

ExtendSelect 

GotFocus 

KeyPress 

LostFocus 

MoveRecord 

NewPageSize 

Notify 

PageDeleted 

PageLoad 

PageSelected 

Resize 

Track 

Trigger 


Description 

The Window object has become the active window. 

The user has started editing a record in a Container object. 

The contents of the object have been changed. 

The user has single-clicked on the object. 

Close has been selected from the system menu. 

The user has collapsed a parent record while in a Container object tree view. 

The user has clicked the right mouse button above a container object. 

The object has been created. 

Another window has become active. 

The object has been destroyed. 

The user has double-clicked on the object. 

The user has dropped a Container object record into the OS/2 Shredder. 

The user had dragged and dropped a record. 

The user had dropped a Container object record into the OS/2 printer. 

The user has finished editing a Container object record. 

The user has expanded the Container object one level while in tree view. 

Controls the way the user selects multiple items. 

The object has input focus. 

A key on the keyboard was pressed. 

The object has lost input focus. 

The user has dropped a record into a Container object. 

A Notebook object page has been resized. 

The DDE Client object has been notified that something has changed. 

A page has been removed from a Notebook object. 

The user has turned to a page in a Notebook object that has no window associated with it. 
A Notebook object page has been selected. 

The Window object has been resized. 

A Slider object slide has been moved. 

A regularly generated event. 
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Methods 

Method 

Accept 

Activate 

AddField 

AddRecord 

AddSharedRecord 

AddString 

AddStringList 

Arrange 

CenterWindow 

Clear 

Copy 

Cut 

Delete 

DeleteList 

DeletePage 

DeleteString 

Deselect 

DeselectList 

Execute 

FindRecord 

FindString 

GetActiveWindow 

GetAttributes 

GetClipboard 

GetFieldAttr 

GetFieldData 

GetFocusWindow 

GetPageNumber 

GetPageWindow 

GetProcessID 

GetRecordAttr 


Description ___ 

Establishes a conversation with a DDE server. 

Activate a Window object. 

Add a field to a Container object. 

Add a record to a Container object. 

Add a shared record to a Container object. 

Add an item to a list of items. 

Add a set of items to a list of items. 

Arrange the records in a Container object. 

Center a window. 

Remove all the items from a list or entry field. 

Copy the selected text to the OS/2 clipboard. 

Copy the selected text to the OS/2 clipboard and then delete it from the object. 

Delete an item from a list of items. 

Delete a set of items from a list of items. 

Remove a page from a Property Notebook. 

Delete an item from a list of items. 

Unselect an item from a list of items. 

Unselect a set of items from a list of items. 

Sends a command to a DDE server. 

Find a given string in the records of a Container object. 

Find an item in a list of items. 

Get the window handle of the active window from the Presentation Manager. 

Get the attributes for items in a ValueSet object. 

Get the contents of the OS/2 clipboard. 

Get the attributes of a field in a Container object. 

Get the value of a field of a record in a Container object. 

Get the window handle of the window with input focus. 

Get the page number corresponding to a given window handle for a Notebook object. 

Get the internal name of the window associated with a given page for a Notebook object. 
Get the process identifier for the current program. 

The attribute for a record in a Container object. 
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Methods (Continued) 


Method Description 


GetRecordList 

GetSelectedList 

GetSelectedStringList 

GetStatusText 

GetString 

GetStringList 

GetTabText 

GetTickLabels 

GetTickSizes 

GetThreadID 

GetVar 

HaltThread 

Initiate 

Insert 

InsertBlankPage 

InsertPage 

InstallAccelerators 

InvokeHelp 

ListChildren 

ListClasses 

ListMethods 

ListPrinters 

ListProperties 

ListThreads 

ListVars 

ListWindows 

LoadClassFile 

Maximize 


Get a list of all the records in a Container object with a particular attribute. 
Returns the number of a set of items from a list of items. 

Returns a set of items from a list of items. 

Get the status text for a given page in a Notebook object. 

Get a single item from a list of items. 

Get all the items in a list. 

Get the tab text for a given page in a Notebook object. 

Get the labels for the ticks on a Slider object. 

Get the sizes of the ticks on a Slider object. 

Get the identification number of the current thread. 

Retrieve a global variable that has been saved with the PutVar method. 

Stop a thread. 

Places all the available DDE servers and topics into a stem variable. 

Insert text into a MultiLine EntryField object. 

Create a blank page for a Notebook object without creating a window for it. 

Insert a window into a Notebook object page. 

Recreate an accelerator table from the menu items. 

Start help for an object just as though the user pressed FI. 

List the children of a GroupBox or Window object. 

List the classes that are available to an application. 

List the methods that are available to an object. 

List all of the installed printers. 

List the properties of an object. 

List all of the active threads in the program. 

List the names of all the variables that have been stored with the PutVar method. 
List all the windows associated with an application. 

Load an object library into an application. 

Maximize a window. 


Minimize Minimize a window. 

Paste Paste text from the OS/2 clipboard. 

Poke Send data to a DDE server._ 
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Methods (Continued) 


Method 

Popup 

Post 

PostKeyString 

PostQueue 

PutClipboard 

PutVar 

RemoveRecord 

Request 

RequestList 

Reset 

Restore 

SendKeyString 

SetAttributes 

SetFieldAttr 

SetFieldData 

SetFocus 

SetPageWindow 

SetRecordAttr 

SetSelectedList 

SetStatusText 

SetStringList 

SetTabText 

SetTickLabels 

SetTickSizes 

SortRecords 

StartThread 

SupportsMethod 

SupportsProperty 

Terminate 

Undo 


Description 
Display a popup menu. 

Add an event string to the topmost event queue of a thread. 

Post a key string to an object. 

Add an event string to the event queue of a thread. 

Put information into the OS/2 clipboard. 

Store global variables that can be retrieved by any program using the GetVar method. 
Remove a record from a Container object. 

Requests information from a DDE server. 

Places data received from a DDE server into a stem variable. 

Reset a list of items to the values the program started with. 

Return a window to its original size. 

Send a key string to an object. 

Set an attribute for each item in a ValueSet object. 

Set the attributes for a field in a Container object. 

Set the field values for a record in a Container object. 

Assign the focus to a particular object. 

Assigns a window to a page in a Notebook object. 

Set an attribute for a record in a Container object. 

Set the selected items in a list. 

Sets the status text for a particular page in a Notebook object. 

Assign a new list of values to a SpinButton object. 

Assign the text for the tab of a page of a Notebook object. 

Assign the tick labels for a Slider object. 

Assign the size of the tick labels for a Slider object. 

Sort the records in a Container object. 

Start a new thread and run a program in it. 

Find out if an object supports a particular method. 

Find out if an object supports a particular property. 

Stops a conservation with a DDE server. 

Reverse the last operation on a MultiLine EntryField object. 
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Properties 

Property 

Accelerator 

AdjustH eight 

AlwaysUpdate 

AutoPosition 

AutoS croll 

AutoSize 

AutoSort 

AutoTab 

BackColor 

Backpages 

Binding 

Border 

BorderColor 

BorderSize 

BorderType 

Cancel 

Caption 

CaptionSeparator 

Checked 

CheckHandles 

ClassName 

Columns 

CommandLine 

Count 

Default 

Defaultltem 

Delay 

DetailSort 

DisableUndo 

DragTarget 


Description 

A keystroke to quickly invoke the Click event of an object. 

Adjust vertical size automatically to show only complete lines. 

Forces a SpinButton object to update each time its value is changed. 

Controls if a Container object automatically positions record icons. 

Controls scrolling in the EntryField object. 

Controls automatic sizing by an object to fit its contents. 

Controls if a Container object sorts new records as they are added. 

Controls moving to next object when text limit has been reached. 

The background color of the object. 

The position of the back pages of a notebook. 

The type of binding to use for a Property Notebook. 

Controls if the object has a border. 

Controls the color of the border of an object. 

Controls the size of the border of an object. 

Controls the type of border of an object. 

Controls if pressing Escape is equivalent to clicking on the button. 

Controls the object's caption. 

Controls if there is a separating line between the caption and contents of a Container object. 
Adds a check mark to a menu item. 

Controls if a Container object checks the validity of record and field handles passed to it. 
The object’s class or type. 

The number of columns of a ValueSet object. 

The command line used to run a VX-REXX program. Does not include the name of the pro¬ 
gram itself. 

The number of items in the list or records of a Container object. 

Controls if pressing Enter is equivalent to clicking on a button. 

The menu item that will be selected in a cascaded menu if the user just clicks on the menu. 
The length of time a Timer object waits between Trigger events. 

Holds the handle of the field used for sorting in a Container object. 

Controls undo in a MultiLine EntryField object. 

Controls the type of objects that can be dropped onto an object_ 
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Properties (Continued) 

Property Description 


Enabled 

ExtendedSelect 

FastSpin 

FirstChild 

FirstRecord 

Flowed 

Font 

ForeColor 

FrameOwner 

Height 

HelpFile 

HelpTag 

HelpText 

HelpTitle 

HideButton 

HiliteColor 

HintText 

HomePosition 

HorizScroll 

HWnd 

IconHeight 

IconWidth 

IgnoreTab 

Index 

InitialList 

InitialPageList 

InteriorHeight 

InteriorLeft 

InteriorTop 

InteriorWidth 


Controls when an object can be used. 

Controls extended selection for ListBox objects of Container object records. 

Controls fast spinning for a SpinButton object. 

The internal name of the first child of an object. 

The handle of the first recorder in a Container object. 

Controls horizontal wrapping of records in a Container object. 

The font used to display text in an object. 

The color an object uses to display text. 

The Presentation Manager window handle of a window’s owner. 

The height of an object. 

The name of the OS/2 IPF help file to search for help. 

The IPF help resource number to use for an object. 

Text that is displayed when the user requests help. 

The title of the window used to show help. 

Controls if a window has a hide button. 

The highlight color for the ValueSet object. 

The hint text of an object. 

The end of a Slider object that has the lowest value. 

Controls horizontal scrollbars on ListBox and MultiLine EntryField objects. 

The OS/2 window handle for an object. 

The height of a standard icon on the screen at the current resolution. 

The width of a standard icon on the screen at the current resolution. 

Controls if the Tab key is used to insert a tab character or move between objects. 

Contains the number of the currently highlighted item in a SpinButton object that is using 
a list of string items. 

The list of items to be displayed with a list or as the items in a ValueSet object. 

The pages that are automatically added to a Property Notebook when it is created. 

The inside height of a window. 

The position of the left interior edge of a window, relative to its enclosing object. 

The position of the top interior edge of a window, relative to its enclosing object. 

The inside width of a window. 
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Properties (Continued) 

Property Description 


ItemBorder 

ItemHeight 

ItemType 

ItemWidth 

Justification 

KeyString 

LastRecord 

LastSplitField 

LayoutStyle 

Left 

MajorTabPos 

Margin 

Masked 

MaximizeButton 

Miniicons 

MinimizeButton 

MoveWithParent 

MultiSelect 

Name 

NumericOnly 

Orientation 

PadWithZeros 

PageCount 

Painting 

Parent 

Percentile 

PicturePath 

Pointer 

PreloadPages 

Program 

Readonly 


Controls the border around items in a ValueSet object. 

The height of each item in a ValueSet object. 

The type of each item in a ValueSet object. 

The width of each item in a ValueSet object. 

Controls the justification of text and the way sliders are positioned. 

A string representing the key that triggered a KeyPress event. 

The handle of the last Container object record. 

Marks the boundary of a Container object when a split bar is present. 

Automates object sizing and positioning according to predefined styles. 

The position of the left edge of an object. 

The position of the major tabs in a Property Notebook. 

The width of the margins of a Slider object along its main axis. 

Controls the masking of characters typed into an EntryField object. 

Controls if a window has a maximize button. 

Controls the size of icons in the Container object. 

Controls if a window has a minimize button. 

Controls if a window moves with its parent. 

Controls if more than one item in ListBox or Container object can be selected at one time. 
The external name of an object. 

Controls the use of nonnumeric values in a SpinButton object. 

Controls the vertical or horizontal orientation of a Slider object. 

Controls padding a SpinButton object with zeros. 

The number of pages in a Property Notebook. 

Controls if changes to an object causes the screen to be updated. 

The internal name of the parent of an object. 

The percentage setting of a Slider object. 

The file name and path of a picture file to be displayed. 

The shape of the mouse pointer. 

Controls automatic loading of Property Notebook pages. 

The file name and path used to run the program. 

Controls if an object can be modified. 
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Properties (Continued) 

Property Description 


ResizePicture 

RibbonColor 

RibbonStrip 

Rows 

Selected 

SelectedEnd 

SelectedStart 

SelectedString 

SelectedText 

Self 

Server 

ServerHWnd 

Set 

ShowCaption 

ShowHints 

ShowTitles 

ShowTreeLine 

ShutDown 

Sibling 

SiblingOrder 

SliderButtons 

SnapToTick 

Sort 

SplitBarLeft 

Status 

StatusArea 

StatusText 

StatusTextAlignment 

SystemMenu 

Tab Group 

Tablndex 


Controls if a picture is rescaled to fit an object. 

Controls the color of the Slider object ribbon strip. 

Controls if the Slider object ribbon strip is colored. 

The number of rows in a ValueSet object. 

The number of the currently selected item in a ListBox or ValueSet object. 
The end position of the selected text in an EntryField object. 

The start position of the selected text in an EntryField object. 

The selected item in a list. 

The selected text in a list. 

The internal name of an object. 

The DDE server the DDE Client object is conversing with. 

The Presentation Manager window handle of the DDE server. 

The current status of a RadioButton or CheckBox object. 

Controls the display of a caption in a Container object. 

Controls the display of hints. 

Controls the display of field titles in the detail view of a Container object. 
Controls connecting a parent and child with a line in a Container object. 
When set, causes a window to shut down. 

The internal name of the next object that has the same parent. 

The ordinal position of the object among its siblings. 

Controls slider buttons on a Slider object. 

Controls if the slider snaps to the nearest tick mark. 

Controls the sort order in a list or Container object. 

Controls the location of the split bar in the Container object. 

The status of a DDE conservation. 

The position of the status area on the window. 

The text displayed in the status area of a window. 

Controls the horizontal alignment of the status text in a Property Notebook. 
Controls showing an OS/2 System menu on a window. 

Creates a new tab group. 

The number of an object in a tabbing sequence. 
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Properties (Continued) 

Property Description 


TabShape 

TabStop 

TabTextAlignment 

TextLimit 

Ticklndex 

TickList 

TickPosition 

Ticks 

TickSize 

Top 

Topic 

Treelndent 

TreeLine 

UserData 

Value 

Vert Justification 

VertScroll 

View 

Visible 

Width 

WindowMode 

WindowState 

WordBreak 

Wordwrap 

WorkingDirectory 


The shape of the tabs on a Property Notebook. 

Controls if an object is included in a tabbing sequence. 

Controls the horizontal alignment style of tab text on a Property Notebook tab. 

The maximum number of characters an object will accept. 

The number of the tick that is closest to setting of a Slider object. 

The tick labels for a Slider object. 

Controls the position of the ticks on a Slider object. 

The number of ticks on a Slider object. 

The size of the ticks on a Slider object. 

The position of the top of an object relative to its enclosing object. 

The topic of a DDE conservation. 

The distance used to indent a child record in a Container object. 

The thickness of the line connecting parent and child records in a container object. 
Arbitrary program defined data. 

The contents of the object. 

Controls the vertical justification of text in an object. 

Controls vertical scroll bars. 

Controls how records are displayed in a Container object. 

Controls if an object can be seen. 

Controls the width of an object. 

Controls the mode of a window. 

Controls the maximized or minimized state of a window. 

Controls whether text is multi-line with word wrapping. 

Controls word wrapping. 

Controls the initial subdirectory of the program. 
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23 

Program Summary 


VX-REXX Programs That Come with This Book 

The following are the VX-REXX example programs included on the CD-ROM that 
comes with this book. 


BatHelp 

BatHelp is a “bonus” program, not discussed in the book. It gathers up all the OS/2 
batch and REXX programs (.CMD) in the current subdirectory and below and dis¬ 
plays their names, full path, and purpose. Displaying a purpose requires a PURPOSE: 
comment in the file, as described in my OS/2 Batch Files to Go and Writing OS/8 
REXX Programs books. This information is displayed in a container object. 

Beeper 

Beeper is a demonstration program that shows how to use Timer object Trigger 
events to automatically schedule actions. Once the user presses on the button to ac¬ 
tivate the beeper, the Trigger event beeps the speaker and alternately turns a De¬ 
scriptive Text object containing the message “Beep” on and off. A Slider object for 
altering the delay between Trigger events and a Descriptive Text object containing a 
title for the Slider object are also made visible while the beeper is on. 

Contain 

The Contain program locates all the icons on the drive from which the program is 
started, starting with the subdirectory and including all subdirectories that branch 
off of it. It then constructs a database containing the icon, its name, subdirectory, 


313 



314 Advanced VX-REXX Topics 


size, creation date, and creation time. PushButton objects allow you to switch be¬ 
tween the seven views supported by the Container object. 

Debug Example 

Debug Example illustrates using the Interactive Debugger. While it contains no bugs, 
several different bugs are temporarily introduced to show what happens. 


Edit 

Edit functions as a very simple editor. You enter the name of a file to edit on the com¬ 
mand line. If it exists, Edit loads it into a Multiline EntryField object for editing. If it 
doesn’t exist, the user is presented with a blank Multiline EntryField object for data en¬ 
try. Clicking on the save button erases the original version of the file and then writes the 
contents of the Multiline EntryField object to that data file. No backup file is created. 

Edit-2 

The Edit program can only edit and save a single data file using the name entered on 
the command line. Edit-2 improves on this by allowing the user to change the name 
under which to save the file and load a new file into memory. Edit-2 also creates a 
backup file in the same subdirectory as the original data file but with a .BAK exten¬ 
sion. This is created before the original data file is erased, so the program is never at 
risk of losing all the data. 

Edit-3 

Edit-3 improves on Edit-2 by asking for confirmation when you try to load another 
file or quit without first saving the file currently in memory. It does this only if the 
currently loaded file has been modified since the last time it was saved. 

Function 

Function displays PushButton objects listing all the actions VX-REXX can perform on 
the OS/2 environment. When the user clicks on a button, it displays the name of the 
appropriate function in one window, a brief explanation of the function in a second 
window, and the syntax in a third window. If the user clicks on another button, the in¬ 
formation is updated to reflect that choice. Function cannot run on a VGA display. 

Fun-2 

Fun-2 is a modified version of the Function program; it uses menus to access the VX- 
REXX function descriptions rather than PushButton objects. Fun-2 cannot run on a 
VGA display. 


Fun-VGA 

Fun-VGA is a modified version of Function, designed to run on a VGA display. It will, 
of course, also run at higher resolutions. 
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Fun2-VGA 

Fun2-VGA is a modified version of Fun-2, designed to run on a VGA display (al¬ 
though it will also run at higher resolutions). Due to its more logical menu arrange¬ 
ment, even users with higher resolutions might prefer this version. 


Get Data 

Get Data is a demonstration program that reads data from the external data queue 
that was placed there by Send Data. The program is stored in the \Q2Q subdirectory. 

In-Line 

This is a demonstration program that uses in-line code to create a thread to beep the 
speaker 20 times. 

ini 

Ini is a sample program that stores the user’s name and age in its own configuration 
file (INI.INI). Its purpose is to demonstrate program configuration. 

Keyboard 

Keyboard presents a simulated keyboard on the screen. The user types by using the 
mouse cursor to click on buttons on the screen. The typed letters then appear on the 
screen above the keyboard. The program automatically handles word wrap on the 
screen, so lines are always broken in between words. As the screen fills up, the text 
scrolls off the screen. To press a shifted key, press the Shift key first. The Shift key 
is “sticky” so the next letter typed will be shifted even though the Shift key isn’t held 
down. After a single shifted key is entered, the Shift key automatically returns to the 
unshifted state. Text cannot be saved or printed, but this would be a simple addition. 

Lines 

Lines scrolls through an ASCII file one line at a time, and displays the current line in 
an EntryField object. The filename is hardwired into the source code as LINES.TXT 
in the current subdirectory. If the user modifies the value, that new value is retained 
in memory. Once the end of the file is reached, the user can continue to scroll for¬ 
wards, adding new lines to the file. In addition to the EntryField object, the program 
has four PushButton objects. They handle scrolling forwards, scrolling backwards, 
saving the data, and exiting the program. There is also a hidden Descriptive Text ob¬ 
ject for displaying an error message if the user tries to scroll backwards once reach¬ 
ing the beginning of the file. 


Line-1 

Line-1 takes the ASCII file entered on the command line and displays it on the screen 
using a series of Descriptive Text objects. Buttons are provided to scroll forwards 
and backwards in case the file is too long to fit on one screen. 
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Listbox 

Listbox is a demonstration program that presents a list of all 16 possible background 
colors in a ListBox object. As you scroll through the list, the background color of the 
ListBox object changes to match the currently highlighted color. If you double-click 
on a color, that color is made the foreground color. (At that point, the color will be 
both the foreground and background color, so the list won’t be visible until you move 
the cursor after double-clicking.) Not all combinations of colors are visible on all 
screens, and the list is never visible when the foreground and background colors are 
the same. Click on the Quit button to exit the program. 

Listbox2 

When you first start Listbox2, it prompts you for the name of an ASCII file from a list. 
Any filename entered on the command line is ignored, but this would be a simple ad¬ 
dition. Once you’ve selected the file, Listbox2 displays its contents in a ListBox ob¬ 
ject. The filename is displayed at the bottom in a Descriptive Text object, and there 
are buttons to load another file and quit the program. 

Lotlines 

Lotlines loads a sample ASCII file into memory and allows the user to scroll around 
the file, making additions and modifications. Lotlines works with a MultiLine Entry- 
Field object. When the entire file fits on one screen, no scrolling is required. When 
the file is too long to fit on one screen, scrolling is handled by the mouse elevator 
that’s automatically added by the MultiLine EntryField object. 

Menu 

Menu is a demonstration program that lets you change the color and caption of a De¬ 
scriptive Text object. Its primary purpose is to demonstrate menu construction. 


Message 

The Message program is designed to be called from the command line to display an 
error message and give the user two alternatives: Continue and Abort. The message 
is taken from the command line and displayed in a Descriptive Text object. After dis¬ 
playing the text, the program waits for the user to click on either PushButton object. 
If the Continue button is clicked, the program supplies a return code of 0. If the 
Abort button is clicked, the program supplies a return code of 1. It’s up to the calling 
program to respond to these return codes. 


Message2 

With Message running, the program that called it might depend on the return 
code it provides to take some action. For this reason, you dont want the user to 
close the program with the System menu. Message2 is a modified version of Mes- 
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sage without the System menu. Additionally, it has a new title and added minimize 
button. This version doesn’t contain a maximize button. 


Music 

The Music program plays a note each time a key is pressed. The interface looks like 
a miniature piano, with the letters A through G on various keys. 

Music-2 

Like Music, Music-2 plays a note each time a key is pressed. It also looks like a minia¬ 
ture piano, with A-G on various keys. 

Music-3 

Like Music-2, Music-3 plays a note each time a key is pressed. Only this time, the 
“keys” are RadioButton objects. Music-3 shows that programs can be configured to 
react to clicked RadioButton objects. 

Music-4 

Music-4 is a modified version of Music-2 that allows the user to load music files from 
disk. As the keys in the file are played, they’re highlighted on the screen so the user 
can follow the music. This might help someone learning to play the piano. A second 
octave of keys has been added that has the sharp keys. Stephen Ginsburg was very 
helpful in developing this program. 

The first line of the music file must be the name of the song, with nothing else 
on that line. The remainder of the file are the notes, with a space, comma, or Re¬ 
turn between notes. Only one divider between notes is allowed. Also, the notes 
must be entered in uppercase. Entering an open parenthesis, (, to the note in¬ 
creases the length of time it’s held. Multiple parentheses can be used and they can 
be placed anywhere in the note. Adding an S to the end of the note makes that 
note sharp. A ! causes the song to pause for the length of one note. Tunes can be 
as long as you like. 

Music-5 

Music-5 is a modified version of Music-4 that adds on-line help. The help is stored in 
two ASCII files (PIANO.TXT and ERROR.TXT), which must be in the same subdi¬ 
rectory as Music-5. 

Notebook 


Notebook is a demonstration program that puts two buttons on the screen. One but¬ 
ton brings up its property notebook, where the user can change the button’s caption, 
size, and color, while the other exits the program. Changes made in the property 
notebook are immediately reflected in the button. 
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Password 

Password is a demonstration program that asks the user for a password as soon as it 
runs. The only valid password is Richardson, and capitalization is important. Once 
the password is entered, the program returns to the primary window where it dis¬ 
plays a message that varies depending on whether or not the correct password was 
entered. At this point, all the user can do is click on a button to exit the program. If 
this were an actual program, it might display a second window like this prior to exit¬ 
ing when an invalid password is entered, while returning the user to the primary win¬ 
dow if a valid password is entered. This would prevent anyone from using the 
program until he or she entered a valid password. 

Pause!! 

This program displays a brief message on the screen and pauses until the user clicks 
on the OK button. The message cannot be changed by the user when the program is 
called. 

Pauselt2 

Pauselt2 is a modified version of Pauselt. It has the System menu turned off, mini¬ 
mize and maximize buttons added, and an expanded title. 

PickFile 

PickFile is a simple demonstration program that displays a dialog box for selecting a 
file when the user clicks on the top button. This choice is displayed in a Descriptive 
Text object, and the user can make another selection by clicking on the button again. 
Clicking on the bottom button terminates the program. 

Pictures 

Pictures is a demonstration program that displays the volume label, amount of space 
in use, amount of free space, and current subdirectory of either the A, B, or C drive. 
Its main purpose, however, is to illustrate the Image PushButton, Image RadioBut- 
ton, and PictureBox objects. 


Post Back 

Post Back is a demonstration program that uses a thread to compute a number and 
then uses the PostQueue method to transfer this information back to the main 
thread, where it’s displayed in a Descriptive Text object. 


Prompt 

Prompt is a demonstration program that shows how to use the VRPrompt function 
to obtain information from the user. In this program, it requests the first name and 
last name, and then displays that information in a Descriptive Text object. 
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Queue 

Queue is a multithreaded demonstration program that immediately starts four 
threads to read data from four external data queues: Ronnyl, Ronny2, Ronny3, and 
Ronny4. If any or all of these queues are in use, it will select its own names. The re¬ 
sults of these four threads are shown on the right side of the screen in separate De¬ 
scriptive Text objects. Initially, these displays will show nothing as nothing has been 
placed in the external data queues. 

Four additional threads are under user control. They can be started from the 
menu or with Ctrl-1 through Ctrl-4. Each of these threads sends data to one of the 
external data queues being read by the original four threads. The lines they place in 
their respective queues are shown in their Descriptive Text object on the left side of 
the screen. Each time one of these threads is invoked, 100 lines of data are placed 
into the queue. Since each Descriptive Text object is serviced by its own thread, all 
eight can be updated at once. 

Sampfe 

Sample simply displays a typical VX-REXX screen with a Descriptive Text object 
showing a brief message, and a PushButton object to click on to exit the program. 


Send Data 

Send Data is a demonstration program that sends 100 lines of data out using the 
Ronnyl REXX external data queue. These 100 lines of data are followed by a TER¬ 
MINATE line. This has no special meaning to REXX or OS/2, but the program that 
reads in the data from the external data queue uses this line as a flag to figure out 
when it has received all the data from the queue. The program is stored in the \Q2Q 
subdirectory. The name of the file is SENDATA. 


ShowEdit 

ShowEdit is a demonstration program whose main purpose is to illustrate drag-and- 
drop programming, covered in Chapter 1. It allows you to enter a line of text in an 
EntryField object, and when you click on a PushButton object that text is trans¬ 
ferred to a Descriptive Text object. 

ShowText 

ShowText is a demonstration program that shows the user a VRMessage box with 
different icons. In this example, the user selects the icon using a RadioButton object 
and then ShowText shows a VRMessage box with four buttons. 

Survey 

Survey is a sample survey program that asks users their gender, age, and income us¬ 
ing RadioButton objects, and which of five major appliances they own using Check- 
Box objects. It performs error-checking to make sure a gender, age, and income are 
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Survey-2 


Survey-3 


Survey-4 


Survey-5 


Survey-6 


Survey-7 


Threads 


entered, displays the results of the last response on the screen, clears all the but¬ 
tons, and waits for a new user to take the survey. It displays an error message when 
the user fails to enter required information. Teachers writing self-graded tests could 
use a very similar approach. 


Survey-2 is a modified version of the Survey program that also asks the users for 
their name and address using a MultiLine EntryField object. This additional infor¬ 
mation is displayed in the Descriptive Text object. 


Survey-3 uses five ComboBox objects to ask users questions about their computer. 
Once a user clicks on the done button, the five responses are displayed in a Descrip¬ 
tive Text object, the five ComboBox objects are returned to their default value, and 
the program is ready to receive another response. 


Survey-4 is a modified version of Survey-3 that uses DropDown ComboBox objects 
rather than ComboBox objects. This reduces the screen real estate required by the 
questions without reducing their functionality. 


Survey-4 uses five DropDown ComboBox objects to ask users five questions about 
their computer system. These boxes take up a lot of space on the screen. Survey-5 
asks these same five questions, only using five SpinButton objects rather than Drop- 
Down ComboBox objects. 


Survey-6 is a modified version of Survey-5 that uses a Slider object to obtain the 
amount of memory and hard-disk space from the user. The CPU, case, and video are 
obtained with a SpinButton object. 


Survey-7 is a modified version of Survey-6 that uses a ValueSet object to obtain the 
case type, screen type, and CPU type, and a Slider object to obtain the amount of 
memory and hard-disk space from the user. 


Threads is a demonstration program that starts and stops four different threads. 
Each thread displays a series of random numbers on the screen. 
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Todo-1 


Todo-2 


Todo-3 


Todo-4 


Todo-5 


ViewBmp 


ViewBmp2 


Viewlcon 


Todo-1 is a to-do program where the items and associated priorities you enter are 
stored in a disk file. It allows you to enter new items, interactively edit existing items, 
delete items, and send finished items to a “done” file. The data is automatically 
sorted when it’s saved. 

There are several different versions of the Todo program on the CD-ROM that 
comes with this book. The book begins by constructing a fairly simple version and 
later adds features. 


Todo-2 improves on Todo-1 by adding a confirmation request when the user erases 
to-do items and tries to exit the program without saving the data if that data has 
been modified. These modifications are accomplished with the VRMessage function. 


Todo-3 improves on Todo-2 by allowing the user to add to-do items and associated 
priorities. This is accomplished with the VRPrompt function. 


Todo-4 is a modified version of Todo-3, where all the on-screen buttons have been 
replaced with a menu. It has also been modified to display a pop-up screen telling 
about the program when that option is selected from the menu. 


Todo-5 is a modified version of Todo-4 in which online help has been added with an 
IPF fhe. 


ViewBmp functions as a file viewer for bitmapped images. Its main PictureBox object 
is empty. The VX-REXX VRFileDialog function lets the user select a bitmapped file 
for viewing, and ViewBmp then displays the image in a PictureBox object. 


ViewBmp2 is a modified version of ViewBmp that uses menus rather than buttons. 


Viewlcon functions as an icon viewer, displaying all the icons in the current subdi¬ 
rectory along with their names. It has room for 49 icons. If there are fewer than 49 
icons, the remaining slots (PictureBox objects) are hidden. If there are more than 49 
icons, scrolling is supported to display the remaining icons. The Forwards button is 
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displayed only when it’s possible to scroll forwards, and the Backwards button is dis¬ 
played only when it’s possible to scroll backwards. Due to its large size, Viewlcon 
won’t run properly on a VGA display. Use VI-VGA instead. 


Viewfcn2 

Viewlcn2 functions as an icon viewer, displaying all the icons on the current hard 
disk, no matter which subdirectory they’re stored in. It has room to display 144 icons 
at a time. If there are fewer than 144 icons, the remaining slots of the ValueSet ob¬ 
ject are filled with a blank icon that was bound into the program. If there are more 
than 144 icons, scrolling is supported to display the remaining icons. The Forwards 
button is displayed only when it’s possible to scroll forwards, and the Backwards but¬ 
ton is displayed only when it’s possible to scroll backwards. Due to its large size, 
Viewlcn2 won’t run properly on a VGA display. Use VI-VGA instead. 

ViewIcnS 

Viewlcn3 is a modified version of Viewlcn2. It has several important modifications. 
They are: 

■ The scrolling and quit buttons have been replaced by a menu. 

■ Due to the extra space on the menu bar, an option has been added to change the 
drive Viewlcn3 uses to search for icons. 

■ Since Viewlcn3 allows the user to look on alternative drives, it also allows the user 
to specify the drive letter to use on the command line after the program name. The 
drive can be specified with or without the colon. 

■ An option has been added to display information on the program. 

Viewlcn3 won’t run properly on a VGA display; use VI-VGA instead. 

VI-VGA 

VI-VGA is a modified version of Viewlcon that will run on a VGA display. It has room 
for only 36 icons at a time. 

VI-VGA2 

VI-VGA2 is a modified version of Viewlcn3 that will run on a VGA display. It has room 
for only 81 icons at a time. 

WC 

WC is a demonstration program that prompts you for the name of a DeScribe docu¬ 
ment and then reports the number of words in that file. DeScribe must be running 
without the requested file loaded in order for WC to work. In addition, the WC and 
WC-GONE DeScribe macros must be installed in the DeScribe macro subdirectory. 
These macros are included in the \EXAMPLES\WC subdirectory along with the WC 
program. 
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WC-Book 

WC-Book is a demonstration program that counts the number of words in a number 
of files. As each file is processed, the results are posted to the D:\BOOK13\WORD- 
COUN.WK3 Lotus worksheet. WC-Book requires the WC and WC-GONE DeScribe 
macros. 

Window-1 

Window-1 is a demonstration program that simply loads three different modeless 
windows when the user clicks on separate PushButton objects. 

Window-2 

Window-2 is a demonstration program that loads a single modal window when the 
user clicks on a PushButton object. In this modal window, it displays the arguments 
passed to the modal window when it was opened. 

Working 

Working is a demonstration program that displays a “Working” message while the 
program performs a long sequence of calculations. This prevents the user from 
thinking the program has “locked up” and trying to abort its operation. The message 
is displayed in a secondary window that’s completely under the control of the pro¬ 
gram itself. 

VX-REXX Sample Programs 

The following programs are included with VX-REXX. The information in the follow¬ 
ing sections summarizes each of the example programs. For more detailed informa¬ 
tion, refer back to Chapter 13. 


Bounce 

Bounce displays an image of the earth against a black background. The image moves 
around the screen in a regular pattern. When it hits one of the four sides, it bounces 
off and continues along its path. 

Button 

Button displays four PushButton objects on the screen. Initially, they’re gray and dis¬ 
play the message “Push Me!” The first time you click on them they change to a red 
background and display “Red.” The next time they change to yellow and display “Yel¬ 
low.” After that, they alternate between red and yellow. 


Calculator 

Calculator is a fairly nice calculator program that performs addition, subtraction, 
multiplication, division, and percentages. It also has a single memory function. 
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DDE Explorer 

DDE Explorer is a sample program that illustrates how to use the DDE Client object 
to interact with applications that support the DDE interface. 


DragDrop 

DragDrop illustrates using the Container object and drag-and-drop function in 
programs. It shows two Container objects on the screen, with four information 
icons in each Container object. As these icons are dragged from one Container ob¬ 
ject and dropped into the other, information about the icons is displayed on the 
screen. 


File Browser 

File Browser displays the files and subdirectories on your hard disk and lets you click 
on different icons to move around the hard disk, viewing the contents of different 
subdirectories. Since it uses a Container object, all the views supported by the Con¬ 
tainer object are supported. It doesn’t let you view the contents of individual files, 
however, as the name might imply. 

Hint and Help 

Hint and Help is a demonstration program that asks users for their name and a pass¬ 
word. However, its main purpose is to illustrate adding hints and help to programs. 

Hocus Focus 

Hocus Focus displays the Presentation Manager handle for the window that cur¬ 
rently has the focus. 

Mind Game 

Mind Game fills a row of four blocks with a random selection of six colors, but doesn’t 
show you the mixture. You then have ten guesses to figure out the color for each of 
the four blocks. After each guess, it tells you how many you got right but doesn’t tell 
you which positions were correct. You use the information from each successive 
guess to narrow your guesses to find the solution. 


MMW 

VX-REXX works with two types of windows: modeless and modal. A modeless win¬ 
dow allows the program that created it and all that program’s children to continue to 
run while it’s active, and a modal window disables the program that created it and all 
that program’s children while it’s running. MMW allows you to click on different 
PushButton objects to create different types of windows. 
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Movies 

Movies demonstrates how to use the multimedia extensions of OS/2 to play movies 
using VX-REXX. You can play the movies using the current thread or in a separate 
thread, so Movies also demonstrates how to use threads. 

Notebook 

Notebook displays a property notebook for a PushButton object, which the user can 
use to change the color and size of the button. Its purpose is to demonstrate how to 
create a property notebook and in this respect is similar to my sample program of the 
same name. 

Popup 

Popup demonstrates how to construct popup menus. In this sample program, these 
menus change the color and caption of three PushButton objects. 

Printing 

Printing is a sample program for sending files to the printer. It uses the ListPrinters 
method and the VRPrintJobDialog and VRPrintFile VX-REXX built-in functions. 

Q+E Text 

Q+E Text displays a database entry screen for employee data. It uses the VXQE and 
QELIB libraries to access the employee database, which is stored in EMP.TXT. 

RGB 

RGB displays three Slider objects and one ValueSet object with four cells. Initially, 
the four cells are colored red, green, blue, and white. Once the user selects a partic¬ 
ular cell in the ValueSet object, he or she can use the three ValueSet objects to alter 
the mixture of red, green, and blue in that cell, thus changing its color. In addition to 
illustrating how to use the Slider and ValueSet objects, this program illustrates how 
to use RGB color settings in a ValueSet object. 

Sample Database 

Sample Database (SampleDB) shows how to use VX-REXX in conjunction with ei¬ 
ther Database 2 OS/2 (DB2/2) or the Extended Services for OS/2 Database Manager 
to manage a small database. (These are separate programs that don’t come with 
OS/2 or VX-REXX, so you might not be able to run this sample program.) Sample 
Database accesses the sample database using the Database Manager REXX applica¬ 
tion programming interface (API) and gives you a simple view of the data. It also 
gives you simple tools to view the data. 
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Scan 

Scan is a macro for the OS/2 Enhanced Editor. It scans the file you’re currently edit¬ 
ing and displays a dialog box listing every REXX label it finds. You then double-click 
on the label name to jump to that point in the file. Scan illustrates using the Make 
Macro option of the Project menu. 

Threads 

VX-REXX has the ability to “spin off’ complex or time-consuming activities to their 
own thread. This thread then runs in the background. This allows the main process 
to continue instead of waiting on the complex or time-consuming activity. Threads 
demonstrates how to create multithreaded applications. 

Update DB Sample 

Like the Sample Database program, Update DB Sample depends on either the Data¬ 
base 2 OS/2 program (DB2/2) or the Extended Services for OS/2 Database Manager 
working with a database. (These are separate programs that don’t come with OS/2 or 
VX-REXX.) Update DB Sample displays employee records from the Staff table of the 
Sample database. The user can delete or modify the viewed records, or add new 
records. 

Window Controller 

Window Controller lists all the open Presentation Manager windows in a Container 
object. It also allows you to send keystrokes to these windows or “shake” them by 
slightly altering their position on the screen. 


Working 

Working is a demonstration program that displays a blinking message while it per¬ 
forms a long series of calculations. VX-REXX lacks the ability to create a blinking 
message. Originally, I tried to use a Timer object to change colors at regular in¬ 
tervals. By alternating the foreground color between a unique color and the back¬ 
ground color, the caption would appear to blink. However, Timer events are 
queued while the program performs calculations, so the colors don’t change while 
the calculations are being performed. Additionally, only one Timer event is 
queued. The solution was to place the message and its associated Timer object on 
a separate thread so the Timer object would operate normally while the main 
thread performed the calculations. 

REXX Programs 

In addition to its many VX-REXX examples, the CD-ROM that comes with this book 
contains a few REXX examples. A few of these are “before” programs, where this 
book shows how to develop a program that performs a similar function under VX- 
REXX. These REXX programs are as follows: 
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GETDATA.CMD 

GETDATA.CMD is a REXX program that place data into an external data queue. 

INTERACT.CMD 

INTERACT.CMD is an external subroutine called by TODO.CMD. It provides inter¬ 
active editing of to-do items. 

UNEOUT.CMD 

LINEOUT.CMD shows that you can use REXX to create multiline files with the Line- 
Out command. 

Queue-i.CMD 

QUEUE-1.CMD demonstrates external data queue management using the RxQueue 
function. 

QUEUE-2.CMD 

QUEUE-2.CMD uses the RXQUEUE.EXE OS/2 filter to pipe the results of an OS/2 
DIR command to an external data queue. It then reads and processes this queue us¬ 
ing REXX commands. 

QUEUE-3.CMD 

QUEUE-3CMD is called by QUEUE-4.CMD. It uses the PARSE PULL instruction to 
get three pieces of information: first name, last name, and age. When run as a stand¬ 
alone program, it reads these from the keyboard and then displays them. When 
called as an external subroutine by QUEUE-4.CMD, QUEUE-4.CMD has already 
placed a first name of Ronny and a last name of Richardson into an external data 
queue, so QUEUE-3.CMD reads these and prompts only for the user’s age. 

QUEUE-4.CMD 

QUEUE-4.CMD places a first and last name, Ronny and Richardson, into an external 
data queue before calling QUEUE-3.CMD as an external subroutine. QUEUE-3.CMD 
reads the first and last name from the external data queue using the PARSE PULL 
instruction and then automatically switches over and reads the age from the key¬ 
board using the same PARSE PULL instruction. 

QUEUE-5.CMD 

QUEUE-5.CMD is called by QUEUE-4.CMD. It uses the Lineln internal function to 
get three pieces of information: first name, last name, and age. When run as a stand¬ 
alone program, it waits forever on the first use of Lineln because no data is waiting 
in the queue, (Press Ctrl-Break to abort). When called as an external subroutine by 
QUEUE-4.CMD, QUEUE-4.CMD has already placed a first and last name, Ronny and 
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Richardson, into an external data queue, so QUEUE-5.CMD reads these and waits 
forever on the third line. (Again, press Ctrl-Break to abort.) 

SENDATA.CMD 

SENDATA.CMD is a REXX program that reads the data in the external data queue 
placed there by GETDATA.CMD. 

SENDATA2.CMD 

SENDATA2.CMD is a REXX program that calls itself as an external subroutine. The 
external subroutine then places data into the external data que, which is then read 
by the calling program. 

TODO.CMD 

TODO.CMD is a simple to-do program. The items and associated priorities you enter 
are stored in a disk file. TODO.CMD allows you to enter new items, interactively edit 
existing items, delete items, and send finished items to a “done” file. The data is au¬ 
tomatically sorted when it’s saved. 
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accelerator keystrokes, 219 
AddString function, 101 
application program interface (API), 249 
applications, multithreaded, 241-248 
ASCII files, 235-236 

B 

Backwards subroutine, 60, 65 
BatHelp program, 313 
Beeper program, 313 
bitmap files, 109 
Bounce program, 171-172, 323 
BuildScreen subroutine, 27-30 
Button program, 172, 323 

c 

Calculator program, 173, 323 
CALL Quit command, 24 
capitalization, 10 
cascaded menus, 217 
Changed subroutine, 65-66 
CheckBox object, 51, 53 
CheckForDoneFile subroutine, 65 
CheckForErrors subroutine, 54 
CheckThisNote subroutine, 205 
Close subroutine, 196-197 
ComboBox object, 103-106 
comment lines, 13 
common user access (CUA), 120 
configuration files, 263-269 
deleting information, 268 
functions for, 264-265 
storing changes, 268 


Contain program, 136-144, 313-314 
Container object, 136-144 
copying, files, 158 
CR_Size_Click subroutine, 135 

D 

date, changing, 158 

DDCB_Foreground_Change subroutine, 133 
DDE Explorer program, 173-174, 324 
DDEClient object, 144 
Debug Example program, 314 
debugging, 285-291 
deleting 

configuration information, 268 
queues, 254 

DeScribe menu, 216, 272-274 
Descriptive Text object, 5-13, 21-31 
directories, sub- (see subdirectories) 
disks 

getting information about, 161-162 
getting label, 163 
Disk subroutine, 112 
DoBook subroutine, 280 
Done subroutine, 66-67, 104, 124, 126 
DragDrop program, 144, 174-177, 324 
drives 

changing, 157 
determining current, 167 
dynamic data exchange (DDE), 271-283 
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Edit program, 80-84, 314 
data format, 82-84 
user interface, 80-82 
Edit-2 program, 87-90, 314 
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Edit-2 program, cont. 
running, 90 
user interface, 87 
VX-REXX coding, 87-90 
Edit-3 program, 92-93, 314 
EF_l_Change subroutine, 132 
EF_Height_Change subroutine, 135-136 
EntryField object, 12, 59-77 
Erase subroutine, 66 
error messages 
getting, 150 
showing multiline, 156 
showing multiple with VRMessageStem, 
94-95 

showing to user, 154-155 
showing with VRMessage function, 90-94 
events 

getting information on last, 151 
getting next, 151 
external data queues, 249-261 
avoiding conflicts, 254-255 
creating new, 251-252 
deleting, 254 
finding active, 254 
getting data from, 253-254 
getting process started, 258-261 
making active, 252 
managing, 251-254 
putting data into, 252-253 
understanding, 250-251 
using in VX-REXX, 255-258 

F 

FigureOut subroutine, 55-56 
File Browser program, 144, 177, 324 
filenames 
picking, 153 
showing full, 166 
splitting into parts, 166-167 
files 

bitmap, 109 

changing attributes, 157 
changing dates/times, 158 
changing type of, 157 
configuration, 263-269 
copying, 158 
creating, 158 
deleting, 160 

determining existence of, 160 
finding/locating, 160 
getting information about, 162-163 
getting OS/2 file type, 163 
getting values from initialization, 161 


listing OS/2 file types, 163 
making .EXE, 5 
managing, 3 
printing, 164 

putting values into initialization, 164 
removing values from initialization, 165 
renaming, 165 

FillListBox subroutine, 102-103 
Fini subroutine, 209 
Forwards subroutine, 61, 67-68 
Fun-2 program, 224, 314 
Fun-VGA program, 314 
Fun2-VGA program, 315 
Function program, 168-169, 314 
functions 
AddString, 101 
configuration file, 264-265 
OS/2 environment, 157-170 
SysFileTree, 130 
ViewBmp, 111 
Viewlcon, 111, 113-114 
VRChAttr, 157, 170 
VRCHDir, 149-150, 158, 170 
VRChDrive, 157, 170 
VRCopyFile, 158,170 
VRCreate, 159, 170 
VRCreateFile, 158,170 
VRCreateStem, 170 
VRCurrDir, 167, 170 
VRCurrDrive, 167, 170 
VRDeleteFile, 160, 170 
VRDellni, 165, 170, 264 
VRDestroy, 165, 170, 196 
VRDir, 162-163, 170 
VRDisklnfo, 161, 170 
VRDiskLabel, 163, 170 
VRError, 150, 169 
VREvent, 151, 169 
VRExpandFileName, 166, 170 
VRFileDate, 158, 170 
VRFileDialog, 85-90, 153,169, 192 
VRFileExists, 160, 170 
VRFindFile, 160, 170 
VRFini, 156, 169 
VRGet, 151, 169 
VRGetFileType, 163, 170 
VRGetlni, 161, 170, 264-265 
VRInfo, 151, 169 
VRInit, 152, 169 
VRIsDir, 163, 170 
VRIsValidObject, 150,169 
VRListFileTypes, 163,170 
VRLoad, 153, 169 

VRLoadSecondary, 152, 169, 195, 198-199 
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VRMessage, 90-94, 154-155, 169,192 
VRMessageStem, 94-95, 156, 169, 192 
VRMethod, 152 
VRMkDir, 159, 170 
VROptions, 154, 169 
VRParseFileName, 166-167, 170 
VRParseFilePath, 167, 170 
VRPrintFile, 164, 170 
VRPrintJobDialog, 159, 170 
VRPrompt, 95-97,155-156, 169, 192 
VRRedirectStdIO, 154, 170 
VRRenameFile, 165, 170 
VRRmDir, 164-165, 170 
VRSet, 23, 154, 169, 196 
VRSetFileType, 157, 170 
VRSetlni, 164, 170, 265 
VRSortStem, 166,170 
VRVersion, 151,169 
VRWindow, 152, 169 
VRWindowPath, 169 
VX-REXX, 149-156 

G 

Get Data program, 256-257, 315 
GetAllIcons subroutine, 113, 127,137 
GetData subroutine, 27, 77-78 
GETDATA.CMD, 250, 327 
GetKeyStroke subroutine, 47-48 
GetNewName subroutine, 89 
Get_Click subroutine, 257 
graphics, 109-118 
GroupBox object, 52 

H 

Help files, 5, 229-240 
ASCII, 235-236 
IPF, 229-232 

property approach, 232-235 
High subroutine, 68 
Hint and Help program, 177-179, 324 
Hocus Focus program, 180, 324 

1 

icons, 109, 138 

Image PushButton object, 110 
Image RadioButton object, 110 
In-Line program, 315 

Information Presentation Facility (IPF), 229 

Ini program, 315 

Init subroutine, 68-69, 122, 266 


input/output (I/O), redirecting, 154 
INTERACT.CMD, 327 
Interactive Debugger, 287-291 
stopping, 291 
tracing, 291 
using, 289-290 

K 

Keyboard program, 43-46, 315 
interface, 43-44, 46 
REXX coding, 46 
Keys subroutine, 114 
Killlt subroutine, 69-70 

L 

Line-1 program, 25-31, 315 
REXX coding, 27-30 
running, 30-31 
user interface, 25-27 
LINEOUT.CMD, 327 
Lines program, 59-61, 315 
ListBox object, 99-103 
Listbox program, 99-102, 316 
cursor movement, 101 
double-clicking, 101-102 
inserting the list, 100-101 
Listbox2 program, 102-103, 316 
LoadFile subroutine, 81 
LoadTune subroutine, 202 
Lotlines program, 77-79, 316 
Lotus 1-2-3 for OS/2, 274-276 
Low subroutine, 69 

M 

macros, DeScribe, 274 
Main subroutine, 245-246, 259-260 
Medium subroutine, 70 
menu bars, 215-217 
Menu Editor, 218-220 
Menu program, 316 
Menu2_Click subroutine, 202 
menus, 215-227 
cascaded,217 
conventions, 217 
creating, 220-222 
creating pop-up, 221-224 
Describe, 216, 272-274 
pop-up, 217 
VX-REXX, 218-227 
Message program, 21-25, 316 
obtaining text from command line, 22-23 
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Message program, cont. 

REXX coding, 24 
running, 25 
user interface, 21-22 
Message2 program, 36-37, 316-317 
messages 

error (see error messages) 
showing and getting long response, 95-97, 
155-156 

Mind Game program, 180, 324 
MMW program, 180-182, 324 
mnemonic, 216 
Modified subroutine, 60, 70 
mouse systems, using to program, 12-19 
Movies program, 182, 325 
MultiLine EntryField object, 77-84 
multithreaded applications, 241-248 
designing, 243 
writing, 243-244 
Music program, 39-40, 317 
interface, 39 
REXX coding, 40 
Music-2 program, 40-43, 317 
interface, 40-41 
REXX coding, 41, 43 
Music-3 program, 57, 317 
Music-4 program, 201-206, 317 
Music-5 program, 317 

N 

NewTodoItem subroutine, 97 
Notebook object, 131-136 
adding, 131-132 
caption page of, 132-133 
color page of, 133 
size page of, 134-136 
Notebook program, 182-184, 317, 325 

o 

objects 

CheckBox, 51, 53 
ComboBox, 103-106 
Container, 136-144 
creating, 159 

creating using stem variable, 159 
DDEClient, 144 
Descriptive Text, 5-13, 21-31 
determining existence of, 150 
EntryField, 12, 59-77 
functions that work with, 150-167 
getting information from, 151 
GroupBox, 52 


Image PushButton, 110 
Image RadioButton, 110-114 
invoking method of, 152 
ListBox, 99-103 
MultiLine EntryField, 77-84 
Notebook, 131-136 
overview, 21 
PictureBox, 109 
PushButton, 5-13, 39-49 
putting information into, 154 
RadioButton, 51 
removing, 165 
Slider, 122-124 
SpinButton, 119-122 
Timer, 145-146 
ValueSet, 124-130 
OK subroutine, 212 
Open subroutine, 195,198 
OS/2 

functions, 157-170 
getting file types, 163 
listing file types, 163 
Lotus 1-2-3 for, 274-276 

p 

Password program, 211-213, 318 
Pauselt program, 33-36, 318 
PB_Configure_Click subroutine, 266 
PB_Demo_Click subroutine, 200 
PB_Load_Click subroutine, 89 
PB_SaveAs_Click subroutine, 88-89 
PB_Start_Click subroutine, 145, 278-279 
PB_Stop_Click subroutine, 146 
PickFile program, 86, 318 
PictureBox object, 109 
pictures (see graphics) 

Pictures program, 110-111, 318 
PlaySong subroutine, 205 
pop-up menus, 217 
creating, 221-224 
Popup program, 184, 325 
Post Back program, 318 
Print subroutine, 71 
printers, customizing settings, 159-160 
printing, files, 164 
Printing program, 184-185, 325 
Process subroutine, 281-283 
ProcessNotes subroutine, 203-204 
programming 
drag-and-drop, 12-19 
multithreaded applications, 241-248 
programs (see also source code) 
BatHelp, 313 



Index 333 


Beeper, 313 
Bounce, 171-172, 323 
Button, 172, 323 
Calculator, 173, 323 
Contain, 136-144, 313-314 
DDE Explorer, 173-174, 324 
Debug Example, 314 
debugging VX-REXX, 285-291 
DragDrop, 144, 174-177, 324 
Edit, 80-84, 314 
Edit-2, 87-90, 314 
Edit-3, 92-93, 314 
File Browser, 144, 177, 324 
Fun-2, 224, 314 
Fun-VGA, 314 
Fun2-VGA, 315 
Function, 314 
Get Data, 256-257,315 
GETDATA.CMD, 250, 327 
Hint and Help, 177-179, 324 
Hocus Focus, 180, 324 
In-Line, 315 
Ini, 315 

INTERACT.CMD, 327 
Keyboard, 43-46, 315 
Line-1,25-31,315 
LINEOUT.CMD, 327 
Lines, 59-61, 315 
Listbox, 99-102, 316 
Listbox2, 102-103, 316 
Lotlines, 77-79, 316 
Menu, 316 
Message, 21-25, 316 
Message2, 36-37, 316-317 
Mind Game, 180, 324 
MMW, 180-182, 324 
Movies, 182, 325 
Music, 39-40, 317 
Music-2, 40-43, 317 
Music-3, 57, 317 
Music-4, 201-206, 317 
Music-5, 317 

Notebook, 182-184, 317, 325 
Password, 211-213, 318 
Pauselt, 33-36, 318 
PickFile, 86, 318 
Pictures, 110-111, 318 
Popup, 184, 325 
Post Back, 318 
Printing, 184-185, 325 
Prompt, 96, 318 
Q+E Text, 185, 325 
Queue, 257-258, 319 
QUEUE-1.CMD, 327 


QUEUE-2.CMD, 327 
QUEUE-3.CMD, 327 
QUEUE-4.CMD, 327 
QUEUE-5.CMD, 327 
RGB, 186, 325 
running, 3 
Sample, 319 
sample VXREXX, 5-12 
SampleDB, 186, 325 
Scan, 186-188, 326 
Send Data, 255-256,319 
SENDATA.CMD, 250, 328 
SENDATA2.CMD, 250, 328 
ShowEdit, 319 
ShowText, 91, 319 
Survey, 51-55, 319-320 
Survey-2, 79-80, 320 
Survey-3, 104-105, 320 
Survey-4, 105, 320 
Survey-5, 119-122, 320 
Survey-6, 122-124, 320 
Survey-7, 124-126, 320 
Threads, 188, 320, 326 
Todo-1, 62-65, 321 
Todo-2, 93-94, 321 
Todo-3, 96-97, 321 
Todo-4, 225-226, 321 
Todo-5, 321 
TODO.CMD, 328 
Update DB Sample, 189, 326 
VI-VGA, 322 
VI-VGA2, 322 
ViewBmp, 321 
ViewBmp2, 321 
Viewlcn2, 126-130, 322 
Viewlcn3, 322 
Viewlcon, 321-322 
WC, 277, 280, 322 
WC-Book, 280, 323 
Window Controller, 189, 326 
Window-1, 323 
Window-2, 323 

Working, 199-201, 246-248, 323, 326 
(see also source code) 

Prompt program, 96, 318 
PushButton object, 5-13, 39-49 

Q 


Q+E Text program, 185, 325 
Queue program, 257-258, 319 
QUEUE-1.CMD, 327 
QUEUE-2.CMD, 327 

QUEUE-3.CMD, 327QUEUE-4.CMD, 327 
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QUEUE-5.CMD, 327-328 
queues 

detached session, 251 
external data, 249-261 
session, 250 
Quit subroutine, 261 
Quit_Click subroutine, 209 

R 

RadioButton object, 51 
Read_Data subroutine, 71 
ResetErrorMessage subroutine, 27 
resource binding, 115-118 
resource identifiers, 109 
RETURN ExitCode command, 24 
REXX Language Association, xix 
RGB program, 186, 325 

s 

Sample program, 319 
SampleDB program, 186, 325 
Save subroutine, 71-72 
SaveData subroutine, 61, 78-79, 81-82, 88 
Scan program, 186-188, 326 
ScrollButtons subroutine, 72-73 
Send Data program, 255-256, 319 
SENDATA.CMD, 250, 328 
SENDATA2.CMD, 250, 328 
Send_Click subroutine, 255-256 
SET command, 26 
SetBackup subroutine, 88 
SetCaption subroutine, 208-209 
SetHeightWidth subroutine, 134 
SetHelp subroutine, 231, 236 
SetTodoItems subroutine, 73-74 
ShowEdit program, 319 
Showlcons subroutine, 114, 128-129 
ShowText program, 91-92, 319 
Size_Create subroutine, 134 
Slider object, 122-124 
sorting, stem variables, 166 
Sort subroutine, 74-75 
source code 

Backwards subroutine, 60, 65 
BuildScreen subroutine, 28-29 
Changed subroutine, 66 
CheckForDoneFile subroutine, 65 
CheckThisNote subroutine, 205 
Close subroutine, 196-197 
CR_Size_Click subroutine, 135 
DDCB_Foreground_Change subroutine, 
133 


Disk subroutine, 112 
DoBook, 280 

Done subroutine, 67, 104, 124, 126 
EF_l_Change, 132 

EF_Height_Change subroutine, 135-136 
FigureOut subroutine, 55-56 
FillListBox, 102-103 
Fini subroutine, 209 
Forwards subroutine, 61, 67 
GetAllIcons subroutine, 113, 127, 137 
GetData subroutine, 77-78 
GetKeyStroke subroutine, 47-48 
GetNewName subroutine, 89 
Get_Click, 257 
High subroutine, 68 
Init subroutine, 68-69, 122, 266 
Keys subroutine, 114 
Killlt subroutine, 69-70 
LoadFile subroutine, 81 
LoadTune subroutine, 202 
Main subroutine, 245-246, 259-260 
Menu2_Click, 202 
Modified subroutine, 60, 70 
NewTodoItem subroutine, 97 
OK subroutine, 212 
Open subroutine, 195, 198 
PB_Configure_Click subroutine, 266 
PB_Demo_Click subroutine, 200 
PB_Load_Click subroutine, 89 
PB_SaveAs_Click subroutine, 88-89 
PB_Start_Click subroutine, 145, 278-279 
PB_Stop_Click subroutine, 146 
PlaySong subroutine, 205 
Print subroutine, 71 
Process subroutine, 281-283 
ProcessNotes subroutine, 203-204 
Quit subroutine, 261 
Quit_Click subroutine, 209 
Read_Data subroutine, 71 
Save subroutine, 72 

SaveData subroutine, 61, 78-79, 81-82, 88 
ScrollButtons subroutine, 72 
Send_Click, 255-256 
SetBackup subroutine, 88 
SetCaption subroutine, 208-209 
SetHeightWidth subroutine, 134 
SetHelp subroutine, 231, 236 
SetTodoItems subroutine, 73-74 
Showlcons subroutine, 114, 128-129 
Size_Create subroutine, 134 
Sort subroutine, 74-75 
StoreToContainer subroutine, 139-140 
Swap subroutine, 75 
ThreadDone subroutine, 246 
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TM_l_Trigger subroutine, 146 
Todo-5.ifp, 237-240 
UnModified subroutine, 75 
VS_l_Click subroutine, 129-130 
VS_Case_Click subroutine, 126 
VS_CPU_Click subroutine, 125 
VS_Screen_Click subroutine, 126 
WindowControl subroutine, 76-77 
Working program, 201 
Working subroutine, 247 
WorkingCode subroutine, 285 
SpinButton object, 119-122 
StoreToContainer subroutine, 139-140 
subdirectories 
changing current, 158 
creating, 159 
determining current, 167 
removing, 164-165 
testing, 163 

subroutines (see source code) 

Survey program, 51-55, 319-320 
REXX coding, 54-55 
user interface, 51-53 
Survey-2 program, 79-80, 320 
Survey-3 program, 104-105, 320 
Survey-4 program, 105, 320 
Survey-5 program, 119-122, 320 
user interface, 119-121 
VX-REXX coding, 122 
Survey-6 program, 122-124, 320 
Survey-7 programs, 124-126, 320 
Swap subroutine, 75 
SysFileTree function, 130 

T 

text, obtaining from command line, 22-23 

ThreadDone subroutine, 246 

threads 

communicating with, 244-246 
multithreaded applications, 241-248 
receiving, 260-261 
sending, 259-260 
starting, 243-244 
stopping, 246 

Threads program, 188, 320, 326 
time, changing, 158 
Timer object, 145-146 
TM_l_Trigger subroutine, 146 
Todo-1 program, 62-65, 321 
user interface, 62-63 
Todo-2 program, 93-94, 321 
Todo-3 program, 96-97, 321 
Todo-4 program, 225-226, 321 
Todo-5 program, 321 


Todo-5.ifp, 237-240 
TODO.CMD, 328 

u 

UnModified subroutine, 75 
Update DB Sample program, 189, 326 

v 

values, selecting from lists, 99-107 
ValueSet object, 124-130 
Vl-VGA program, 322 
VI-VGA2 program, 322 
ViewBmp program, 111, 321 
ViewBmp2 program, 321 
Viewlcn2 program, 126-130, 322 
Viewlcn3 program, 322 
Viewlconfunction, 111, 113-114 
Viewlcon program, 321-322 
VRChAttr function, 157, 170 
VRChDir function, 149-150, 158, 170 
VRChDrive function, 157, 170 
VRCopyFile function, 158, 170 
VRCreate function, 159, 170 
VRCreateFile function, 158, 170 
VRCreateStem function, 159, 170 
VRCurrDir function, 167, 170 
VRCurrDrive function, 167, 170 
VRDeleteFile function, 160, 170 
VRDellni function, 165, 170, 264 
VRDestroy function, 165, 170, 196 
VRDir function, 162-163, 170 
VRDisklnfo function, 161, 170 
VRDiskLabel function, 163, 170 
VRError function, 150, 169 
VREvent function, 151, 169 
VRExpandFileName function, 166, 170 
VRFileDate function, 158, 170 
VRFileDialog function, 85-90, 153, 169, 192 
VRFileExists function, 160, 170 
VRFindFile function, 160, 170 
VRFini function, 156, 169 
VRGet function, 151, 169 
VRGetFileType function, 163, 170 
VRGetlni function, 161, 170, 264-265 
VRInfo function, 151, 169 
VRInit function, 152, 169 
VRIsDir function, 163, 170 
VRIsValidObject function, 150, 169 
VRListFileTypes function, 163, 170 
VRLoad function, 153, 169 
VRLoadSecondary function, 152, 169, 195, 
198-199 
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VRMessage function, 90-94, 154-155,169, 192 
VRMessageStem function, 94-95, 156,169,192 
VRMethod function, 152, 169 
VRMkDir function, 159, 170 
VROptions function, 154, 169 
VRParseFileName function, 166-167, 170 
VRParseFilePath function, 167, 170 
VRPrintFile function, 164, 170 
VRPrintJobDialog function, 159-160, 170 
VRPrompt function, 95-97, 155-156, 169, 192 
VRRedirectStdIO function, 154, 170 
VRRenameFile function, 165, 170 
VRRmDir function, 164-165, 170 
VRSet function, 23, 154, 169, 196 
VRSetFileType function, 157, 170 
VRSetlni function, 164, 170, 265 
VRSortStem function, 166, 170 
VRVersion function, 151, 169 
VRWindow function, 152, 169 
VRWindowPath function, 169 
VS_l_Click subroutine, 129-130 
VS_Case_Click subroutine, 126 
VS_CPU_Click subroutine, 125 
VS_Screen_Click subroutine, 126 
VX-REXX, 1-19 
DDE in, 276-283 

drag-and-drop programming, 12-19 

functions, 149-156 

getting help (see help files) 

getting version number, 151 

initializing programming environment, 152 

making .EXE files, 5 

managing files, 3 

menus, 218-227 

running programs, 3 

sample program, 5-12 

setting runtime options, 154 

starting, 2-3 

summaries, 293-311 

terminating programming environment, 156 


w 

WC program, 277, 280, 322 
WC-Book program, 280, 323 
Weeks, Steve, 274 

Window Controller program, 189, 326 
Window-1 program, 323 
Window-2 program, 323 
WindowControl subroutine, 75-77 
windows, 33-38 

closing modal secondary while program is 
running, 209-210 

closing modeless secondary while program 
is running, 196-197 
creating modal secondary, 207 
creating modeless secondary, 193-194 
getting name of, 152 
loading description from file, 153 
loading secondary description from file, 

152 

Message2 program, 36-37 
modal, 191,206-210 
modeless, 191-197 
Pauselt program, 33-36 
positioning, 197-199 
primary, 191-192, 207 
returning a value to primary, 209 
secondary, 191-192 

using modal secondary while program is 
running, 208-209 

using modeless secondary while program is 
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